CosmosClient Class

A client-side logical representation of an Azure Cosmos DB account.

Use this client to configure and execute requests to the Azure Cosmos DB service.

It's recommended to maintain a single instance of CosmosClient per lifetime of the application which enables efficient connection management and performance.

CosmosClient initialization is a heavy operation - don't use initialization CosmosClient instances as credentials or network connectivity validations.

Instantiate a new CosmosClient.

Inheritance

builtins.object

CosmosClient

Constructor

CosmosClient(url: str, credential: str | Dict[str, str] | AsyncTokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Parameters

Name	Description
url Required	str The URL of the Cosmos DB account.
credential Required	Union[str, Dict[str, str], AsyncTokenCredential] Can be the account key, or a dictionary of resource tokens.

Keyword-Only Parameters

Name	Description
consistency_level	str Consistency level to use for the session. Default value is None (account-level). More on consistency levels and possible values: https://aka.ms/cosmos-consistency-levels
timeout	int An absolute timeout in seconds, for the combined HTTP request and response processing.
connection_timeout	int The HTTP request timeout in seconds.
connection_mode	str The connection mode for the client - currently only supports 'Gateway'.
proxy_config	ProxyConfiguration Connection proxy configuration.
ssl_config	SSLConfiguration Connection SSL configuration.
connection_verify	bool Whether to verify the connection, default value is True.
connection_cert	str An alternative certificate to verify the connection.
retry_total	int Maximum retry attempts.
retry_backoff_max	int Maximum retry wait time in seconds.
retry_fixed_interval	int Fixed retry interval in milliseconds.
retry_read	int Maximum number of socket read retry attempts.
retry_connect	int Maximum number of connection error retry attempts.
retry_status	int Maximum number of retry attempts on error status codes.
retry_on_status_codes	list[int] A list of specific status codes to retry on.
retry_backoff_factor	float Factor to calculate wait time between retry attempts.
enable_endpoint_discovery	bool Enable endpoint discovery for geo-replicated database accounts. (Default: True)
preferred_locations	list[str] The preferred locations for geo-replicated database accounts.
enable_diagnostics_logging	bool Enable the CosmosHttpLogging policy. Must be used along with a logger to work.
logger	Logger Logger to be used for collecting request diagnostics. Can be passed in at client level (to log all requests) or at a single request level. Requests will be logged at INFO level.

Examples

Create a new instance of the Cosmos DB client:

       async with CosmosClient(url, key) as client:

Methods

close	Close this instance of CosmosClient.
create_database	Create a new database with the given ID (name).
create_database_if_not_exists	Create the database if it does not exist already. If the database already exists, the existing settings are returned. ..note:: This function does not check or update existing database settings or offer throughput if they differ from what is passed in.
delete_database	Delete the database with the given ID (name).
from_connection_string	Create a CosmosClient instance from a connection string. This can be retrieved from the Azure portal.For full list of optional keyword arguments, see the CosmosClient constructor.
get_database_client	Retrieve an existing database with the ID (name) id.
list_databases	List the databases in a Cosmos DB SQL database account.
query_databases	Query the databases in a Cosmos DB SQL database account.

close

Close this instance of CosmosClient.

async close() -> None

create_database

Create a new database with the given ID (name).

async create_database(id: str, *, offer_throughput: int | ThroughputProperties | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> DatabaseProxy

Parameters

Name	Description
id Required	str ID (name) of the database to create.

Keyword-Only Parameters

Name	Description
offer_throughput	Union[int, ThroughputProperties] The provisioned throughput for this offer.
session_token	str Token for use with Session consistency.
initial_headers	dict[str, str] Initial headers to be sent as part of the request.
etag	str An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition	MatchConditions The match condition to use upon the etag.
response_hook	Callable[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.

Returns

Type	Description
DatabaseProxy	A DatabaseProxy instance representing the new database.

Exceptions

Type	Description
CosmosResourceExistsError	Database with the given ID already exists.

Examples

Create a database in the Cosmos DB account:

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

Create the database if it does not exist already.

If the database already exists, the existing settings are returned.

..note:: This function does not check or update existing database settings or offer throughput if they differ from what is passed in.

async create_database_if_not_exists(id: str, *, offer_throughput: int | ThroughputProperties | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> DatabaseProxy

Parameters

Name	Description
id Required	str ID (name) of the database to read or create.

Keyword-Only Parameters

Name	Description
offer_throughput	Union[int, ThroughputProperties] The provisioned throughput for this offer.
session_token	str Token for use with Session consistency.
initial_headers	dict[str, str] Initial headers to be sent as part of the request.
etag	str An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition	MatchConditions The match condition to use upon the etag.
response_hook	Callable[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.

Returns

Type	Description
DatabaseProxy	A DatabaseProxy instance representing the database.

Exceptions

Type	Description
CosmosHttpResponseError	The database read or creation failed.

delete_database

Delete the database with the given ID (name).

async delete_database(database: str | DatabaseProxy | Dict[str, Any], *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> None

Parameters

Name	Description
database Required	Union[str, DatabaseProxy, Dict[str, Any]] The ID (name), dict representing the properties, or DatabaseProxy instance of the database to delete.

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency.
initial_headers	dict[str, str] Initial headers to be sent as part of the request.
etag	str An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition	MatchConditions The match condition to use upon the etag.
response_hook	Callable[[Dict[str, str]], None] A callable invoked with the response metadata.

Returns

Type	Description
None

Exceptions

Type	Description
CosmosHttpResponseError	If the database couldn't be deleted.

from_connection_string

Create a CosmosClient instance from a connection string.

This can be retrieved from the Azure portal.For full list of optional keyword arguments, see the CosmosClient constructor.

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parameters

Name	Description
conn_str Required	str The connection string.

Keyword-Only Parameters

Name	Description
credential	Union[str, Dict[str, str]] Alternative credentials to use instead of the key provided in the connection string.
consistency_level	str Consistency level to use for the session. Default value is None (account-level). More on consistency levels and possible values: https://aka.ms/cosmos-consistency-levels

Returns

Type	Description
CosmosClient	a CosmosClient instance

get_database_client

Retrieve an existing database with the ID (name) id.

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Parameters

Name	Description
database Required	Union[str, DatabaseProxy, Dict[str, Any]] The ID (name), dict representing the properties, or DatabaseProxy instance of the database to get.

Returns

Type	Description
DatabaseProxy	A DatabaseProxy instance representing the retrieved database.

list_databases

List the databases in a Cosmos DB SQL database account.

list_databases(*, max_item_count: int | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Keyword-Only Parameters

Name	Description
max_item_count	int Max number of items to be returned in the enumeration operation.
session_token	str Token for use with Session consistency.
initial_headers	dict[str, str] Initial headers to be sent as part of the request.
response_hook	Callable[[Dict[str, str]], None] A callable invoked with the response metadata.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, str]]	An AsyncItemPaged of database properties (dicts).

query_databases

Query the databases in a Cosmos DB SQL database account.

query_databases(query: str, *, parameters: List[Dict[str, Any]] | None = None, max_item_count: int | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	Union[str, Dict[str, Any]] The Azure Cosmos DB SQL query to execute.

Keyword-Only Parameters

Name	Description
parameters	List[Dict[str, Any]] Optional array of parameters to the query. Each parameter is a dict() with 'name' and 'value' keys.
max_item_count	int Max number of items to be returned in the enumeration operation.
session_token	str Token for use with Session consistency.
initial_headers	dict[str, str] Initial headers to be sent as part of the request.
response_hook	Callable[[Dict[str, str]], None] A callable invoked with the response metadata.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, str]]	An AsyncItemPaged of database properties (dicts).