CosmosClient class

Package:

@azure/cosmos

Provides a client-side logical representation of the Azure Cosmos DB database account. This client is used to configure and execute requests in the Azure Cosmos DB database service.

Example

Instantiate a client and create a new database

const client = new CosmosClient({endpoint: "<URL HERE>", key: "<KEY HERE>"});
await client.databases.create({id: "<database name here>"});

Example

Instantiate a client with custom Connection Policy

const client = new CosmosClient({
   endpoint: "<URL HERE>",
   key: "<KEY HERE>",
   connectionPolicy: {
    requestTimeout: 10000,
   },
});

Constructors

CosmosClient(CosmosClientOptions)	Creates a new CosmosClient object. See CosmosClientOptions for more details on what options you can use.
CosmosClient(string)	Creates a new CosmosClient object from a connection string. Your database connection string can be found in the Azure Portal

Properties

databases	Used for creating new databases, or querying/reading all databases. Use .database(id) to read, replace, or delete a specific, existing database by id. Example Create a new database const {resource: databaseDefinition, database} = await client.databases.create({id: "<name here>"});
offers	Used for querying & reading all offers. Use .offer(id) to read, or replace existing offers.

Methods

database(string)	Used for reading, updating, or deleting a existing database by id or accessing containers belonging to that database. This does not make a network call. Use .read to get info about the database after getting the Database object. Example Create a new container off of an existing database const container = client.database("<database id>").containers.create("<container id>"); Example Delete an existing database await client.database("<id here>").delete();
dispose()	Clears background endpoint refresher. Use client.dispose() when destroying the CosmosClient within another process.
getDatabaseAccount(RequestOptions)	Get information about the current DatabaseAccount (including which regions are supported, etc.)
getReadEndpoint()	Gets the currently used read endpoint. Useful for troubleshooting purposes. The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
getReadEndpoints()	Gets the currently used read endpoint. Useful for troubleshooting purposes. The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
getWriteEndpoint()	Gets the currently used write endpoint url. Useful for troubleshooting purposes. The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
getWriteEndpoints()	Gets the known write endpoints. Useful for troubleshooting purposes. The urls may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.
offer(string)	Used for reading, or updating a existing offer by id.

Constructor Details

CosmosClient(CosmosClientOptions)

Creates a new CosmosClient object. See CosmosClientOptions for more details on what options you can use.

new CosmosClient(options: CosmosClientOptions)

Parameters

options

CosmosClientOptions

bag of options; require at least endpoint and auth to be configured

CosmosClient(string)

Creates a new CosmosClient object from a connection string. Your database connection string can be found in the Azure Portal

new CosmosClient(connectionString: string)

Parameters

connectionString

string

Property Details

databases

Used for creating new databases, or querying/reading all databases.

Use .database(id) to read, replace, or delete a specific, existing database by id.

Example

Create a new database

const {resource: databaseDefinition, database} = await client.databases.create({id: "<name here>"});

databases: Databases

Property Value

Databases

offers

Used for querying & reading all offers.

Use .offer(id) to read, or replace existing offers.

offers: Offers

Property Value

Offers

Method Details

database(string)

Used for reading, updating, or deleting a existing database by id or accessing containers belonging to that database.

This does not make a network call. Use .read to get info about the database after getting the Database object.

Example

Create a new container off of an existing database

const container = client.database("<database id>").containers.create("<container id>");

Example

Delete an existing database

await client.database("<id here>").delete();

function database(id: string): Database

Parameters

id

string

The id of the database.

Returns

Database

dispose()

Clears background endpoint refresher. Use client.dispose() when destroying the CosmosClient within another process.

function dispose()

getDatabaseAccount(RequestOptions)

Get information about the current DatabaseAccount (including which regions are supported, etc.)

function getDatabaseAccount(options?: RequestOptions): Promise<ResourceResponse<DatabaseAccount>>

Parameters

options

RequestOptions

Returns

Promise<ResourceResponse<DatabaseAccount>>

getReadEndpoint()

Gets the currently used read endpoint. Useful for troubleshooting purposes.

The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.

function getReadEndpoint(): Promise<string>

Returns

Promise<string>

getReadEndpoints()

Gets the currently used read endpoint. Useful for troubleshooting purposes.

The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.

function getReadEndpoints(): Promise<readonly string[]>

Returns

Promise<readonly string[]>

getWriteEndpoint()

Gets the currently used write endpoint url. Useful for troubleshooting purposes.

The url may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.

function getWriteEndpoint(): Promise<string>

Returns

Promise<string>

getWriteEndpoints()

Gets the known write endpoints. Useful for troubleshooting purposes.

The urls may contain a region suffix (e.g. "-eastus") if we're using location specific endpoints.

function getWriteEndpoints(): Promise<readonly string[]>

Returns

Promise<readonly string[]>

offer(string)

Used for reading, or updating a existing offer by id.

function offer(id: string): Offer

Parameters

id

string

The id of the offer.

Returns

Offer