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.
Its 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.objectCosmosClient
Constructor
CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)
Parameters
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
Keyword-Only Parameters
- 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_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)
- 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:
from azure.cosmos import exceptions, CosmosClient, PartitionKey
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, **kwargs: Any) -> DatabaseProxy
Parameters
- id
ID (name) of the database to create.
- offer_throughput
The provisioned throughput for this offer.
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- 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
A callable invoked with the response metadata.
Returns
A DatabaseProxy instance representing the new database.
Return type
Exceptions
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, **kwargs: Any) -> DatabaseProxy
Parameters
- id
ID (name) of the database to read or create.
- offer_throughput
- int or <xref:azure.cosmos.ThroughputProperties.>
The provisioned throughput for this offer.
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- 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
A callable invoked with the response metadata.
Returns
A DatabaseProxy instance representing the database.
Return type
Exceptions
The database read or creation failed.
delete_database
Delete the database with the given ID (name).
delete_database(database: str | DatabaseProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None
Parameters
- database
- str or dict(str, str) or DatabaseProxy
The ID (name), dict representing the properties or <xref:azure.cosmos.cosmos_client.DatabaseProxy> instance of the database to delete.
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- 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
A callable invoked with the response metadata.
Return type
Exceptions
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: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient
Parameters
Alternative credentials to use instead of the key provided in the connection string.
Consistency level to use for the session. The default value is None (Account level).
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- 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
A callable invoked with the response metadata.
Exceptions
Database with the given ID already exists.
get_database_account
Retrieve the database account information.
get_database_account(**kwargs: Any) -> DatabaseAccount
Keyword-Only Parameters
- response_hook
- Callable
A callable invoked with the response metadata.
Returns
A DatabaseAccount instance representing the Cosmos DB Database Account.
Return type
Exceptions
Database with the given ID already exists.
get_database_client
Retrieve an existing database with the ID (name) id.
get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy
Parameters
- database
- str or dict(str, str) or DatabaseProxy
The ID (name), dict representing the properties or DatabaseProxy instance of the database to read.
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- 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
A callable invoked with the response metadata.
Returns
A DatabaseProxy instance representing the retrieved database.
Return type
Exceptions
Database with the given ID already exists.
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, **kwargs: Any) -> Iterable[Dict[str, Any]]
Parameters
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- response_hook
- Callable
A callable invoked with the response metadata.
Returns
An Iterable of database properties (dicts).
Return type
Exceptions
Database with the given ID already exists.
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, **kwargs: Any) -> Iterable[Dict[str, Any]]
Parameters
Optional array of parameters to the query. Ignored if no query is provided.
- enable_cross_partition_query
- bool
Allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.
Keyword-Only Parameters
- session_token
- str
Token for use with Session consistency.
- response_hook
- Callable
A callable invoked with the response metadata.
Returns
An Iterable of database properties (dicts).
Return type
Exceptions
Database with the given ID already exists.
Azure SDK for Python
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for