Share via

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.
retry_write
int

Indicates how many times the SDK should automatically retry write operations for items, even if the operation is not guaranteed to be idempotent. This should only be enabled if the application can tolerate such risks or has logic to safely detect and handle duplicate operations.
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.
excluded_locations
list[str]

The excluded locations to be skipped from preferred locations. The locations in this list are specified as the names of the azure Cosmos locations like, 'West US', 'East US' and so on. If all preferred locations were excluded, primary/hub location will be used.
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 write operations for items.
throughput_bucket
int

The desired throughput bucket for the client
user_agent_suffix
str

Allows user agent suffix to be specified when creating client

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, *, offer_throughput: int | ThroughputProperties | None = None, initial_headers: dict[str, str] | None = None, response_hook: Callable[[Mapping[str, Any]], None] | None = None, throughput_bucket: int | None = None, return_properties: Literal[False] = False, **kwargs: Any) -> DatabaseProxy

Parameters

Name Description
args
Required
Any

args
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 database.
initial_headers
dict[str, str]

Initial headers to be sent as part of the request.
response_hook
Callable[[Mapping[str, Any]], None]

A callable invoked with the response metadata.
throughput_bucket
int

The desired throughput bucket for the client
return_properties
bool

Specifies whether to return either a DatabaseProxy or a Tuple containing a DatabaseProxy and the associated database properties.

Returns

Type Description
DatabaseProxy,
tuple [DatabaseProxy, CosmosDict]

A DatabaseProxy instance representing the database or a tuple of DatabaseProxy and CosmosDict with the database properties.

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, *, offer_throughput: int | ThroughputProperties | None = None, initial_headers: dict[str, str] | None = None, response_hook: Callable[[Mapping[str, Any]], None] | None = None, throughput_bucket: int | None = None, return_properties: Literal[False] = False, **kwargs: Any) -> DatabaseProxy

Parameters

Name Description
args
Required
Any

args
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 database.
initial_headers
dict[str, str]

Initial headers to be sent as part of the request.
response_hook
Callable[[Mapping[str, Any]], None]

A callable invoked with the response metadata.
throughput_bucket
int

The desired throughput bucket for the client
return_properties
bool

Specifies whether to return either a DatabaseProxy or a Tuple containing a DatabaseProxy and the associated database properties.

Returns

Type Description
DatabaseProxy,
tuple [DatabaseProxy, CosmosDict]

A DatabaseProxy instance representing the database or a tuple of DatabaseProxy and CosmosDict with the database properties.

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, *, initial_headers: dict[str, str] | None = None, response_hook: Callable[[Mapping[str, Any]], None] | None = None, throughput_bucket: int | None = None, **kwargs: Any) -> None

Parameters

Name Description
database
Required
Union[str, dict[str, str], DatabaseProxy]

The ID (name), dict representing the properties or DatabaseProxy instance of the database to delete.
populate_query_metrics
Default value: None

Keyword-Only Parameters

Name Description
initial_headers
dict[str, str]

Initial headers to be sent as part of the request.

Default value: None
response_hook
Callable[[Mapping[str, str]], None]

A callable invoked with the response metadata.

Default value: None
throughput_bucket
int

The desired throughput bucket for the client

Default value: None

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(*, response_hook: Callable[[Mapping[str, Any]], None] | None = None, **kwargs) -> DatabaseAccount

Keyword-Only Parameters

Name Description
response_hook
Callable[[Mapping[str, Any]], None]

A callable invoked with the response metadata.

Default value: None

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, *, initial_headers: dict[str, str] | None = None, response_hook: Callable[[Mapping[str, Any]], None] | None = None, throughput_bucket: int | 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
initial_headers
dict[str, str]

Initial headers to be sent as part of the request.

Default value: None
response_hook
Callable[[Mapping[str, str]], None]

A callable invoked with the response metadata.

Default value: None
throughput_bucket
int

The desired throughput bucket for the client

Default value: None

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, *, initial_headers: dict[str, str] | None = None, response_hook: Callable[[Mapping[str, Any]], None] | None = None, throughput_bucket: int | None = None, **kwargs: Any) -> ItemPaged[dict[str, Any]]

Parameters

Name Description
query
str

The Azure Cosmos DB SQL query to execute. If not specified, the method will get all databases.

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
initial_headers
dict[str, str]

Initial headers to be sent as part of the request.

Default value: None
response_hook
Callable[[Mapping[str, str]], None]

A callable invoked with the response metadata.

Default value: None
throughput_bucket
int

The desired throughput bucket for the client

Default value: None

Returns

Type Description
Iterable[dict[str, str]]

An Iterable of database properties (dicts).