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.

Constructor

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

Parameters

Name	Description
url Required	str The URL of the Cosmos DB account.
credential Required	Union[str, Dict[str, str], TokenCredential] Can be the account key, or a dictionary of resource tokens.
consistency_level	str Consistency level to use for the session. The default value is None (Account level). More on consistency levels and possible values: https://aka.ms/cosmos-consistency-levels Default value: None

Keyword-Only Parameters

Name	Description
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.
no_response_on_write	bool Indicates whether service should be instructed to skip sending response payloads on rite operations for items.

Examples

Create a new instance of the Cosmos DB client:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey
   from typing import Dict, Any

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Methods

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_account	Retrieve the database account information.
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.

create_database

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

create_database(id: str, populate_query_metrics: bool | None = None, 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.
offer_throughput	Union[int, ThroughputProperties] The provisioned throughput for this offer. Default value: None
populate_query_metrics	Default value: None

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency. Default value: None
initial_headers	Dict[str, str] Initial headers to be sent as part of the request. Default value: None
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. Default value: None
match_condition	MatchConditions The match condition to use upon the etag. Default value: None
response_hook	Callable 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 = 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.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, 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.
populate_query_metrics	bool Enable returning query metrics in response headers. Default value: None
offer_throughput	Union[int, ThroughputProperties] The provisioned throughput for this offer. Default value: None

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency. Default value: None
initial_headers	Dict[str, str] Initial headers to be sent as part of the request. Default value: None
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. Default value: None
match_condition	MatchConditions The match condition to use upon the etag. Default value: None
response_hook	Callable 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).

delete_database(database: str | DatabaseProxy | Mapping[str, Any], populate_query_metrics: bool | 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) -> None

Parameters

Name	Description
database Required	Union[str, Dict[str, str], DatabaseProxy] The ID (name), dict representing the properties or <xref:azure.cosmos.cosmos_client.DatabaseProxy> instance of the database to delete.
populate_query_metrics	Default value: None

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency. Default value: None
initial_headers	Dict[str, str] Initial headers to be sent as part of the request. Default value: None
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. Default value: None
match_condition	MatchConditions The match condition to use upon the etag. Default value: None
response_hook	Callable 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: TokenCredential | str | Dict[str, Any] | None = None, consistency_level: str | None = None, **kwargs) -> CosmosClient

Parameters

Name	Description
conn_str Required	str The connection string.
credential	Union[str, Dict[str, str]] Alternative credentials to use instead of the key provided in the connection string. Default value: None
consistency_level	str Consistency level to use for the session. The default value is None (Account level). Default value: None

Returns

Type	Description
CosmosClient	A CosmosClient instance representing the new client.

get_database_account

Retrieve the database account information.

get_database_account(**kwargs) -> DatabaseAccount

Keyword-Only Parameters

Name	Description
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
DatabaseAccount	A DatabaseAccount instance representing the Cosmos DB Database Account.

get_database_client

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

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

Parameters

Name	Description
database Required	str or dict(str, str) or DatabaseProxy The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.

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, populate_query_metrics: bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
max_item_count	int Max number of items to be returned in the enumeration operation. Default value: None
populate_query_metrics	Default value: None

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency. Default value: None
initial_headers	Dict[str, str] Initial headers to be sent as part of the request. Default value: None
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
Iterable[Dict[str, str]]	An Iterable of database properties (dicts).

query_databases

Query the databases in a Cosmos DB SQL database account.

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

Parameters

Name	Description
query	str The Azure Cosmos DB SQL query to execute. Default value: None
parameters	List[Dict[str, Any]] Optional array of parameters to the query. Ignored if no query is provided. Default value: None
enable_cross_partition_query	bool Allow scan on the queries which couldn't be served as indexing was opted out on the requested paths. Default value: None
max_item_count	int Max number of items to be returned in the enumeration operation. Default value: None
populate_query_metrics	Default value: None

Keyword-Only Parameters

Name	Description
session_token	str Token for use with Session consistency. Default value: None
initial_headers	Dict[str, str] Initial headers to be sent as part of the request. Default value: None
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
Iterable[Dict[str, str]]	An Iterable of database properties (dicts).