azure.cosmos package

class azure.cosmos.CosmosClient(url: str, credential: Any, consistency_level: str = 'Session', **kwargs: Any)

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.

Parameters

• url (str) – The URL of the Cosmos DB account.

• credential (str or dict[str, str]) – 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 “Session”.

Keyword Arguments

• timeout (int) – An absolute timeout in seconds, for the combined HTTP request and response processing.

• request_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.

Example:

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)

Instantiate a new CosmosClient.

create_database(id: str, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, **kwargs: Any) → azure.cosmos.database.DatabaseProxy

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

Parameters

• id – ID (name) of the database to create.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

• offer_throughput (int) – The provisioned throughput for this offer.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A DatabaseProxy instance representing the new database.

Return type

DatabaseProxy

Raises

CosmosResourceExistsError – Database with the given ID already exists.

Example:

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(id: str, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, **kwargs: Any) → azure.cosmos.database.DatabaseProxy

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.

Parameters

• id – ID (name) of the database to read or create.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

• offer_throughput (int) – The provisioned throughput for this offer.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A DatabaseProxy instance representing the database.

Return type

DatabaseProxy

Raises

CosmosHttpResponseError – The database read or creation failed.

delete_database(database: Union[str, azure.cosmos.database.DatabaseProxy, Dict[str, Any]], populate_query_metrics: Optional[bool] = None, **kwargs: Any) → None

Delete the database with the given ID (name).

Parameters

• database (str or dict(str, str) or DatabaseProxy) – The ID (name), dict representing the properties or DatabaseProxy instance of the database to delete.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – If the database couldn’t be deleted.

Return type

None

classmethod from_connection_string(conn_str: str, credential: Optional[Any] = None, consistency_level: str = 'Session', **kwargs: Any) → azure.cosmos.cosmos_client.CosmosClient

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.

Parameters

• conn_str (str) – The connection string.

• credential (str or 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. The default value is “Session”.

get_database_account(**kwargs: Any) → azure.cosmos.documents.DatabaseAccount

Retrieve the database account information.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A DatabaseAccount instance representing the Cosmos DB Database Account.

Return type

DatabaseAccount

get_database_client(database: Union[str, azure.cosmos.database.DatabaseProxy, Dict[str, Any]]) → azure.cosmos.database.DatabaseProxy

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

Parameters

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

Returns

A DatabaseProxy instance representing the retrieved database.

Return type

DatabaseProxy

list_databases(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the databases in a Cosmos DB SQL database account.

Parameters

• max_item_count (int) – Max number of items to be returned in the enumeration operation.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of database properties (dicts).

Return type

Iterable[dict[str, str]]

query_databases(query: Optional[str] = None, parameters: Optional[List[str]] = None, enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Query the databases in a Cosmos DB SQL database account.

Parameters

• query (str) – The Azure Cosmos DB SQL query to execute.

• parameters (list[str]) – 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.

• max_item_count (int) – Max number of items to be returned in the enumeration operation.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of database properties (dicts).

Return type

Iterable[dict[str, str]]

class azure.cosmos.DatabaseProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, id: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific database.

This class should not be instantiated directly. Instead use the CosmosClient.get_database_client() method.

A database contains one or more containers, each of which can contain items, stored procedures, triggers, and user-defined functions.

A database can also have associated users, each of which is configured with a set of permissions for accessing certain containers, stored procedures, triggers, user-defined functions, or items.

Variables

id – The ID (name) of the database.

An Azure Cosmos DB SQL API database has the following system-generated properties. These properties are read-only:

• _rid: The resource ID.

• _ts: When the resource was last updated. The value is a timestamp.

• _self: The unique addressable URI for the resource.

• _etag: The resource etag required for optimistic concurrency control.

• _colls: The addressable path of the collections resource.

• _users: The addressable path of the users resource.

Parameters

• client_connection (ClientSession) – Client from which this database was retrieved.

• id (str) – ID (name) of the database.

create_container(id: str, partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, unique_key_policy: Optional[Dict[str, Any]] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

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

If a container with the given ID already exists, a CosmosResourceExistsError is raised.

Parameters

• id – ID (name) of container to create.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• populate_query_metrics – Enable returning query metrics in response headers.

• offer_throughput – The provisioned throughput for this offer.

• unique_key_policy – The unique key policy to apply to the container.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A ContainerProxy instance representing the new container.

Raises

CosmosHttpResponseError – The container creation failed.

Return type

ContainerProxy

Example:

Create a container with default settings:

container_name = "products"
try:
    container = database.create_container(
        id=container_name, partition_key=PartitionKey(path="/productName")
    )
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(container_name)

Create a container with specific settings; in this case, a custom partition key:

customer_container_name = "customers"
try:
    customer_container = database.create_container(
        id=customer_container_name,
        partition_key=PartitionKey(path="/city"),
        default_ttl=200,
    )
except exceptions.CosmosResourceExistsError:
    customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, unique_key_policy: Optional[Dict[str, Any]] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

Create a container if it does not exist already.

If the container already exists, the existing settings are returned. Note: it does not check or update the existing container settings or offer throughput if they differ from what was passed into the method.

Parameters

• id – ID (name) of container to read or create.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• populate_query_metrics – Enable returning query metrics in response headers.

• offer_throughput – The provisioned throughput for this offer.

• unique_key_policy – The unique key policy to apply to the container.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A ContainerProxy instance representing the container.

Raises

CosmosHttpResponseError – The container read or creation failed.

Return type

ContainerProxy

create_user(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Create a new user in the container.

To update or replace an existing user, use the ContainerProxy.upsert_user() method.

Parameters

body – A dict-like object with an id key and value representing the user to be created. The user ID must be unique within the database, and consist of no more than 255 characters.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the new user.

Raises

CosmosHttpResponseError – If the given user couldn’t be created.

Return type

UserProxy

Example:

Create a database user:

try:
    database.create_user(dict(id="Walter Harp"))
except exceptions.CosmosResourceExistsError:
    print("A user with that ID already exists.")
except exceptions.CosmosHttpResponseError as failure:
    print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]], populate_query_metrics: Optional[bool] = None, **kwargs: Any) → None

Delete a container.

Parameters

• container – The ID (name) of the container to delete. You can either pass in the ID of the container to delete, a ContainerProxy instance or a dict representing the properties of the container.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – If the container couldn’t be deleted.

Return type

None

delete_user(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]], **kwargs: Any) → None

Delete the specified user from the container.

Parameters

user – The ID (name), dict representing the properties or UserProxy instance of the user to be deleted.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The user wasn’t deleted successfully.

• CosmosResourceNotFoundError – The user does not exist in the container.

Return type

None

get_container_client(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]]) → azure.cosmos.container.ContainerProxy

Get a ContainerProxy for a container with specified ID (name).

Parameters

container – The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.

Return type

ContainerProxy

Example:

Get an existing container, handling a failure if encountered:

database = client.get_database_client(database_name)
container = database.get_container_client(container_name)

get_user_client(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]]) → azure.cosmos.user.UserProxy

Get a UserProxy for a user with specified ID.

Parameters

user – The ID (name), dict representing the properties or UserProxy instance of the user to be retrieved.

Returns

A UserProxy instance representing the retrieved user.

Raises

CosmosHttpResponseError – If the given user couldn’t be retrieved.

Return type

UserProxy

list_containers(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the containers in the database.

Parameters

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of container properties (dicts).

Return type

Iterable[dict[str, Any]]

Example:

List all containers in the database:

database = client.get_database_client(database_name)
for container in database.list_containers():
    print("Container ID: {}".format(container.id))

list_users(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the users in the container.

Parameters

max_item_count – Max number of users to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of user properties (dicts).

Return type

Iterable[dict[str, Any]]

query_containers(query: Optional[str] = None, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the properties for containers in the current database.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of container properties (dicts).

Return type

Iterable[dict[str, Any]]

query_users(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all users matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of users to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of user properties (dicts).

Return type

Iterable[str, Any]

read(populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Dict[str, Any]

Read the database properties.

Parameters

populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Return type

Dict[Str, Any]

Raises

CosmosHttpResponseError – If the given database couldn’t be retrieved.

read_offer(**kwargs: Any) → azure.cosmos.offer.Offer

Read the Offer object for this database.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the database.

Raises

CosmosHttpResponseError – If no offer exists for the database or if the offer could not be retrieved.

Return type

Offer

replace_container(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]], partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

Reset the properties of the container.

Property changes are persisted immediately. Any properties not specified will be reset to their default values.

Parameters

• container – The ID (name), dict representing the properties or ContainerProxy instance of the container to be replaced.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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.

• initial_headers (dict[str,str]) – Initial headers to be sent as part of the request.

• response_hook (Callable) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – Raised if the container couldn’t be replaced. This includes if the container with given id does not exist.

Returns

A ContainerProxy instance representing the container after replace completed.

Return type

ContainerProxy

Example:

Reset the TTL property on a container, and display the updated properties:

# Set the TTL on the container to 3600 seconds (one hour)
database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

# Display the new TTL setting for the container
container_props = database.get_container_client(container_name).read()
print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput(throughput: Optional[int], **kwargs: Any) → azure.cosmos.offer.Offer

Replace the database-level throughput.

Parameters

throughput – The throughput to be set (an integer).

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the database, updated with new throughput.

Raises

CosmosHttpResponseError – If no offer exists for the database or if the offer could not be updated.

Return type

Offer

replace_user(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Replaces the specified user if it exists in the container.

Parameters

• user – The ID (name), dict representing the properties or UserProxy instance of the user to be replaced.

• body – A dict-like object representing the user to replace.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the user after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the user with given ID does not exist.

Return type

UserProxy

upsert_user(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Insert or update the specified user.

If the user already exists in the container, it is replaced. If the user does not already exist, it is inserted.

Parameters

body – A dict-like object representing the user to update or insert.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the upserted user.

Raises

CosmosHttpResponseError – If the given user could not be upserted.

Return type

UserProxy

class azure.cosmos.ContainerProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, database_link: str, id: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific DB Container.

This class should not be instantiated directly. Instead, use the DatabaseProxy.get_container_client() method to get an existing container, or the Database.create_container() method to create a new container.

A container in an Azure Cosmos DB SQL API database is a collection of documents, each of which is represented as an Item.

Variables

• id (str) – ID (name) of the container

• session_token (str) – The session token for the container.

create_item(body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, indexing_directive: Optional[Any] = None, **kwargs: Any) → Dict[str, str]

Create an item in the container.

To update or replace an existing item, use the ContainerProxy.upsert_item() method.

Parameters

• body – A dict-like object representing the item to create.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

• indexing_directive – Indicate whether the document should be omitted from indexing.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the new item.

Raises

CosmosHttpResponseError – Item with the given ID already exists.

Return type

dict[str, Any]

delete_conflict(conflict: Union[str, Dict[str, Any]], partition_key: Any, **kwargs: Any) → None

Delete a specified conflict from the container.

If the conflict does not already exist in the container, an exception is raised.

Parameters

• conflict – The ID (name) or dict representing the conflict to be deleted.

• partition_key – Partition key for the conflict to delete.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The conflict wasn’t deleted successfully.

• CosmosResourceNotFoundError – The conflict does not exist in the container.

Return type

None

delete_item(item: Union[Dict[str, Any], str], partition_key: Any, populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → None

Delete the specified item from the container.

If the item does not already exist in the container, an exception is raised.

Parameters

• item – The ID (name) or dict representing item to be deleted.

• partition_key – Specifies the partition key value for the item.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The item wasn’t deleted successfully.

• CosmosResourceNotFoundError – The item does not exist in the container.

Return type

None

get_conflict(conflict: Union[str, Dict[str, Any]], partition_key: Any, **kwargs: Any) → Dict[str, str]

Get the conflict identified by conflict.

Parameters

• conflict – The ID (name) or dict representing the conflict to retrieve.

• partition_key – Partition key for the conflict to retrieve.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the retrieved conflict.

Raises

CosmosHttpResponseError – The given conflict couldn’t be retrieved.

Return type

dict[str, Any]

list_conflicts(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the conflicts in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

Iterable[dict[str, Any]]

query_conflicts(query: str, parameters: Optional[List[str]] = None, enable_cross_partition_query: Optional[bool] = None, partition_key: Optional[Any] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all conflicts matching a given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• enable_cross_partition_query – Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.

• partition_key – Specifies the partition key value for the item.

• max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

Iterable[dict[str, Any]]

query_items(query: str, parameters: Optional[List[str]] = None, partition_key: Optional[Any] = None, enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, enable_scan_in_query: Optional[bool] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all results matching the given query.

You can use any value for the container name in the FROM clause, but often the container name is used. In the examples below, the container name is “products,” and is aliased as “p” for easier referencing in the WHERE clause.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• partition_key – Specifies the partition key value for the item.

• enable_cross_partition_query – Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.

• max_item_count – Max number of items to be returned in the enumeration operation.

• enable_scan_in_query – Allow scan on the queries which couldn’t be served as indexing was opted out on the requested paths.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

Example:

Get all products that have not been discontinued:

import json

for item in container.query_items(
    query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
    enable_cross_partition_query=True,
):
    print(json.dumps(item, indent=True))

Parameterized query to get all products that have been discontinued:

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
    parameters=[dict(name="@model", value="DISCONTINUED")],
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

query_items_change_feed(partition_key_range_id: Optional[str] = None, is_start_from_beginning: bool = False, continuation: Optional[str] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Get a sorted list of items that were changed, in the order in which they were modified.

Parameters

• partition_key_range_id – ChangeFeed requests can be executed against specific partition key ranges. This is used to process the change feed in parallel across multiple consumers.

• is_start_from_beginning – Get whether change feed should start from beginning (true) or from current (false). By default it’s start from current (false).

• continuation – e_tag value to be used as continuation for reading change feed.

• max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

read(populate_query_metrics: Optional[bool] = None, populate_partition_key_range_statistics: Optional[bool] = None, populate_quota_info: Optional[bool] = None, **kwargs: Any) → Dict[str, Any]

Read the container properties.

Parameters

• populate_query_metrics – Enable returning query metrics in response headers.

• populate_partition_key_range_statistics – Enable returning partition key range statistics in response headers.

• populate_quota_info – Enable returning collection storage quota information in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – Raised if the container couldn’t be retrieved. This includes if the container does not exist.

Returns

Dict representing the retrieved container.

Return type

dict[str, Any]

read_all_items(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the items in the container.

Parameters

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

read_item(item: Union[str, Dict[str, Any]], partition_key: Any, populate_query_metrics: Optional[bool] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Get the item identified by item.

Parameters

• item – The ID (name) or dict representing item to retrieve.

• partition_key – Partition key for the item to retrieve.

• populate_query_metrics – Enable returning query metrics in response headers.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

Dict representing the item to be retrieved.

Raises

CosmosHttpResponseError – The given item couldn’t be retrieved.

Return type

dict[str, Any]

Example:

Get an item from the database and update one of its properties:

item = container.read_item("item2", partition_key="Widget")
item["productModel"] = "DISCONTINUED"
updated_item = container.upsert_item(item)

read_offer(**kwargs: Any) → azure.cosmos.offer.Offer

Read the Offer object for this container.

If no Offer already exists for the container, an exception is raised.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the container.

Raises

CosmosHttpResponseError – No offer exists for the container or the offer could not be retrieved.

Return type

Offer

replace_item(item: Union[str, Dict[str, Any]], body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Replaces the specified item if it exists in the container.

If the item does not already exist in the container, an exception is raised.

Parameters

• item – The ID (name) or dict representing item to be replaced.

• body – A dict-like object representing the item to replace.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the item after replace went through.

Raises

CosmosHttpResponseError – The replace failed or the item with given id does not exist.

Return type

dict[str, Any]

replace_throughput(throughput: int, **kwargs: Any) → azure.cosmos.offer.Offer

Replace the container’s throughput.

If no Offer already exists for the container, an exception is raised.

Parameters

throughput – The throughput to be set (an integer).

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the container, updated with new throughput.

Raises

CosmosHttpResponseError – No offer exists for the container or the offer could not be updated.

Return type

Offer

upsert_item(body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Insert or update the specified item.

If the item already exists in the container, it is replaced. If the item does not already exist, it is inserted.

Parameters

• body – A dict-like object representing the item to update or insert.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the upserted item.

Raises

CosmosHttpResponseError – The given item could not be upserted.

Return type

dict[str, Any]

property is_system_key

property scripts

class azure.cosmos.PartitionKey(path, kind='Hash', version=2)

Key used to partition a container into logical partitions.

See https://docs.microsoft.com/azure/cosmos-db/partitioning-overview#choose-partitionkey for information on how to choose partition keys.

Variables

• path – The path of the partition key

• kind – What kind of partition key is being defined (default: “Hash”)

• version – The version of the partition key (default: 2)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys()

Returns a new dict with keys from iterable and values equal to value.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D’s items

keys() → a set-like object providing a view on D’s keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D’s values

property kind

property path

property version

class azure.cosmos.Permission(id: str, user_link: str, permission_mode: Union[str, azure.cosmos.documents.PermissionMode], resource_link: str, properties: Dict[str, Any])

Represents a Permission object in the Azure Cosmos DB SQL API service.

class azure.cosmos.ScriptsProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, container_link: str, is_system_key: bool)

An interface to interact with stored procedures.

This class should not be instantiated directly. Instead, use the ContainerProxy.scripts() attribute.

create_stored_procedure(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a new stored procedure in the container.

To replace an existing sproc, use the Container.scripts.replace_stored_procedure() method.

Parameters

body – A dict-like object representing the sproc to create.

Returns

A dict representing the new stored procedure.

Raises

CosmosHttpResponseError – If the given stored procedure couldn’t be created.

Return type

dict[str, Any]

create_trigger(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a trigger in the container.

To replace an existing trigger, use the ContainerProxy.scripts.replace_trigger() method.

Parameters

body – A dict-like object representing the trigger to create.

Returns

A dict representing the new trigger.

Raises

CosmosHttpResponseError – If the given trigger couldn’t be created.

Return type

dict[str, Any]

create_user_defined_function(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a user-defined function in the container.

To replace an existing UDF, use the ContainerProxy.scripts.replace_user_defined_function() method.

Parameters

body – A dict-like object representing the udf to create.

Returns

A dict representing the new user-defined function.

Raises

CosmosHttpResponseError – If the user-defined function couldn’t be created.

Return type

dict[str, Any]

delete_stored_procedure(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified stored procedure from the container.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

sproc – The ID (name) or dict representing stored procedure to be deleted.

Raises

• CosmosHttpResponseError – The sproc wasn’t deleted successfully.

• CosmosResourceNotFoundError – The sproc does not exist in the container.

Return type

None

delete_trigger(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified trigger from the container.

If the trigger does not already exist in the container, an exception is raised.

Parameters

trigger – The ID (name) or dict representing trigger to be deleted.

Raises

• CosmosHttpResponseError – The trigger wasn’t deleted successfully.

• CosmosResourceNotFoundError – The trigger does not exist in the container.

Return type

None

delete_user_defined_function(udf: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified user-defined function from the container.

If the UDF does not already exist in the container, an exception is raised.

Parameters

udf – The ID (name) or dict representing udf to be deleted.

Raises

• CosmosHttpResponseError – The udf wasn’t deleted successfully.

• CosmosResourceNotFoundError – The UDF does not exist in the container.

Return type

None

execute_stored_procedure(sproc: Union[str, Dict[str, Any]], partition_key: Optional[str] = None, params: Optional[List[Any]] = None, enable_script_logging: Optional[bool] = None, **kwargs: Any) → Any

Execute a specified stored procedure.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

• sproc – The ID (name) or dict representing stored procedure to be executed.

• partition_key – Specifies the partition key to indicate which partition the sproc should execute on.

• params – List of parameters to be passed to the stored procedure to be executed.

• enable_script_logging (bool) – Enables or disables script logging for the current request.

Returns

Result of the executed stored procedure for the given parameters.

Raises

CosmosHttpResponseError – If the stored procedure execution failed or if the stored procedure with given id does not exists in the container.

Return type

dict[str, Any]

get_stored_procedure(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get the stored procedure identified by id.

Parameters

sproc – The ID (name) or dict representing stored procedure to retrieve.

Returns

A dict representing the retrieved stored procedure.

Raises

CosmosHttpResponseError – If the given stored procedure couldn’t be retrieved.

Return type

dict[str, Any]

get_trigger(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get a trigger identified by id.

Parameters

trigger – The ID (name) or dict representing trigger to retrieve.

Returns

A dict representing the retrieved trigger.

Raises

CosmosHttpResponseError – If the given trigger couldn’t be retrieved.

Return type

dict[str, Any]

get_user_defined_function(udf: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get a user-defined functions identified by id.

Parameters

udf – The ID (name) or dict representing udf to retrieve.

Returns

A dict representing the retrieved user-defined function.

Raises

CosmosHttpResponseError – If the user-defined function couldn’t be retrieved.

Return type

Iterable[dict[str, Any]]

list_stored_procedures(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all stored procedures in the container.

Parameters

max_item_count (int) – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of stored procedures (dicts).

Return type

Iterable[dict[str, Any]]

list_triggers(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all triggers in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of triggers (dicts).

Return type

Iterable[dict[str, Any]]

list_user_defined_functions(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the user-defined functions in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of user-defined functions (dicts).

Return type

Iterable[dict[str, Any]]

query_stored_procedures(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all stored procedures matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of stored procedures (dicts).

Return type

Iterable[dict[str, Any]]

query_triggers(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all triggers matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of triggers (dicts).

Return type

Iterable[dict[str, Any]]

query_user_defined_functions(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return user-defined functions matching a given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of user-defined functions (dicts).

Return type

Iterable[dict[str, Any]]

replace_stored_procedure(sproc: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified stored procedure in the container.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

• sproc – The ID (name) or dict representing stored procedure to be replaced.

• body – A dict-like object representing the sproc to replace.

Returns

A dict representing the stored procedure after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the stored procedure with given id does not exist.

Return type

dict[str, Any]

replace_trigger(trigger: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified tigger in the container.

If the trigger does not already exist in the container, an exception is raised.

Parameters

• trigger – The ID (name) or dict representing trigger to be replaced.

• body – A dict-like object representing the trigger to replace.

Returns

A dict representing the trigger after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the trigger with given id does not exist.

Return type

dict[str, Any]

replace_user_defined_function(udf: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified user-defined function in the container.

If the UDF does not already exist in the container, an exception is raised.

Parameters

• udf – The ID (name) or dict representing udf to be replaced.

• body – A dict-like object representing the udf to replace.

Returns

A dict representing the user-defined function after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the user-defined function with the given id does not exist.

Return type

dict[str, Any]

class azure.cosmos.UserProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, id: str, database_link: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific user.

This class should not be instantiated directly. Instead, use the DatabaseProxy.get_user_client() method.

create_permission(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Create a permission for the user.

To update or replace an existing permision, use the UserProxy.upsert_permission() method.

Parameters

body – A dict-like object representing the permission to create.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the new permission.

Raises

CosmosHttpResponseError – If the given permission couldn’t be created.

Return type

dict[str, Any]

delete_permission(permission: str, **kwargs: Any) → None

Delete the specified permission from the user.

If the permission does not already exist, an exception is raised.

Parameters

permission – The ID (name), dict representing the properties or Permission instance of the permission to be replaced.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The permission wasn’t deleted successfully.

• CosmosResourceNotFoundError – The permission does not exist for the user.

Return type

None

get_permission(permission: str, **kwargs: Any) → azure.cosmos.permission.Permission

Get the permission identified by id.

Parameters

permission – The ID (name), dict representing the properties or Permission instance of the permission to be retrieved.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the retrieved permission.

Raises

CosmosHttpResponseError – If the given permission couldn’t be retrieved.

Return type

dict[str, Any]

list_permissions(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all permission for the user.

Parameters

max_item_count – Max number of permissions to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of permissions (dicts).

Return type

Iterable[dict[str, Any]]

query_permissions(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all permissions matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of permissions to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of permissions (dicts).

Return type

Iterable[dict[str, Any]]

read(**kwargs: Any) → Dict[str, Any]

Read user propertes.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dictionary of the retrieved user properties.

Raises

CosmosHttpResponseError – If the given user couldn’t be retrieved.

Return type

dict[str, Any]

replace_permission(permission: str, body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Replaces the specified permission if it exists for the user.

If the permission does not already exist, an exception is raised.

Parameters

• permission – The ID (name), dict representing the properties or Permission instance of the permission to be replaced.

• body – A dict-like object representing the permission to replace.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the permission after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the permission with given id does not exist.

Return type

dict[str, Any]

upsert_permission(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Insert or update the specified permission.

If the permission already exists in the container, it is replaced. If the permission does not exist, it is inserted.

Parameters

• body – A dict-like object representing the permission to update or insert.

• response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the upserted permission.

Raises

CosmosHttpResponseError – If the given permission could not be upserted.

Return type

dict[str, Any]

class azure.cosmos.Offer(offer_throughput: int, properties: Optional[Dict[str, Any]] = None)

Represents a offer in an Azure Cosmos DB SQL API container.

To read and update offers use the associated methods on the Container.

class azure.cosmos.DatabaseAccount

Database account.

A DatabaseAccount is the container for databases.

Variables

• DatabaseLink (str) – The self-link for Databases in the databaseAccount.

• MediaLink (str) – The self-link for Media in the databaseAccount.

• MaxMediaStorageUsageInMB (int) – Attachment content (media) storage quota in MBs (Retrieved from gateway).

• CurrentMediaStorageUsageInMB (int) – Current attachment content (media) usage in MBs (Retrieved from gateway). Value is returned from cached information updated periodically and is not guaranteed to be real time.

• ConsistencyPolicy (dict) – UserConsistencyPolicy settings.

• ConsistencyPolicy['defaultConsistencyLevel'] (dict) – The default consistency level.

• ConsistencyPolicy['maxStalenessPrefix'] (int) – In bounded staleness consistency, the maximum allowed staleness in terms difference in sequence numbers (aka version).

• ConsistencyPolicy['maxStalenessIntervalInSeconds'] (int) – In bounded staleness consistency, the maximum allowed staleness in terms time interval.

• EnableMultipleWritableLocations (boolean) – Flag on the azure Cosmos account that indicates if writes can take place in multiple locations.

property ReadableLocations

The list of readable locations for a geo-replicated database account.

property WritableLocations

The list of writable locations for a geo-replicated database account.

class azure.cosmos.ConsistencyLevel

Represents the consistency levels supported for Azure Cosmos client operations.

The requested ConsistencyLevel must match or be weaker than that provisioned for the database account. Consistency levels.

Consistency levels by order of strength are Strong, BoundedStaleness, Session, ConsistentPrefix and Eventual.

Variables

• ConsistencyLevel.Strong (str) – Strong Consistency guarantees that read operations always return the value that was last written.

• ConsistencyLevel.BoundedStaleness (str) – Bounded Staleness guarantees that reads are not too out-of-date. This can be configured based on number of operations (MaxStalenessPrefix) or time (MaxStalenessIntervalInSeconds).

• ConsistencyLevel.Session (str) – Session Consistency guarantees monotonic reads (you never read old data, then new, then old again), monotonic writes (writes are ordered) and read your writes (your writes are immediately visible to your reads) within any single session.

• ConsistencyLevel.Eventual (str) – Eventual Consistency guarantees that reads will return a subset of writes. All writes will be eventually be available for reads.

• ConsistencyLevel.ConsistentPrefix (str) – ConsistentPrefix Consistency guarantees that reads will return some prefix of all writes with no gaps. All writes will be eventually be available for reads.

BoundedStaleness = 'BoundedStaleness'

ConsistentPrefix = 'ConsistentPrefix'

Eventual = 'Eventual'

Session = 'Session'

Strong = 'Strong'

class azure.cosmos.DataType

Specifies the data type of index specs.

Variables

• Number (str) – Represents a numeric data type.

• String (str) – Represents a string data type.

• Point (str) – Represents a point data type.

• LineString (str) – Represents a line string data type.

• Polygon (str) – Represents a polygon data type.

• MultiPolygon (str) – Represents a multi-polygon data type.

LineString = 'LineString'

MultiPolygon = 'MultiPolygon'

Number = 'Number'

Point = 'Point'

Polygon = 'Polygon'

String = 'String'

class azure.cosmos.IndexKind

Specifies the index kind of index specs.

Variables

• IndexKind.Hash (str) – The index entries are hashed to serve point look up queries. Can be used to serve queries like: SELECT * FROM docs d WHERE d.prop = 5

• IndexKind.Range (str) – The index entries are ordered. Range indexes are optimized for inequality predicate queries with efficient range scans. Can be used to serve queries like: SELECT * FROM docs d WHERE d.prop > 5

Hash = 'Hash'

Range = 'Range'

class azure.cosmos.IndexingMode

Specifies the supported indexing modes.

Variables

• Consistent (str) –

  Index is updated synchronously with a create or update operation. With consistent indexing, query behavior is the same as the default consistency level for the collection.

  The index is always kept up to date with the data.

• Lazy (str) –

  Index is updated asynchronously with respect to a create or update operation.

  With lazy indexing, queries are eventually consistent. The index is updated when the collection is idle.

• NoIndex (str) –

  No index is provided.

  Setting IndexingMode to “None” drops the index. Use this if you don’t want to maintain the index for a document collection, to save the storage cost or improve the write throughput. Your queries will degenerate to scans of the entire collection.

Consistent = 'consistent'

Lazy = 'lazy'

NoIndex = 'none'

class azure.cosmos.PermissionMode

Enumeration specifying applicability of a permission.

Variables

• PermissionMode.NoneMode (str) – None.

• PermissionMode.Read (str) – Permission applicable for read operations only.

• PermissionMode.All (str) – Permission applicable for all operations.

All = 'all'

NoneMode = 'none'

Read = 'read'

class azure.cosmos.ProxyConfiguration

Configuration for a proxy.

Variables

• Host (str) – The host address of the proxy.

• Port (int) – The port number of the proxy.

class azure.cosmos.SSLConfiguration

Configuration for SSL connections.

See https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification for more information.

Variables

• SSLKeyFIle (str) – The path of the key file for ssl connection.

• SSLCertFile (str) – The path of the cert file for ssl connection.

• SSLCaCerts (str) – The path of the CA_BUNDLE file with certificates of trusted CAs.

class azure.cosmos.TriggerOperation

Specifies the operations on which a trigger should be executed.

Variables

• TriggerOperation.All (str) – All operations.

• TriggerOperation.Create (str) – Create operations only.

• TriggerOperation.Update (str) – Update operations only.

• TriggerOperation.Delete (str) – Delete operations only.

• TriggerOperation.Replace (str) – Replace operations only.

All = 'all'

Create = 'create'

Delete = 'delete'

Replace = 'replace'

Update = 'update'

class azure.cosmos.TriggerType

Specifies the type of a trigger.

Variables

• TriggerType.Pre (str) – Trigger should be executed before the associated operation(s).

• TriggerType.Post (str) – Trigger should be executed after the associated operation(s).

Post = 'post'

Pre = 'pre'

class azure.cosmos.ConnectionRetryPolicy(**kwargs)

configure_retries(options)

Configures the retry settings.

Parameters

options – keyword arguments from context.

Returns

A dict containing settings and history for retries.

Return type

dict

get_backoff_time(settings)

Returns the current backoff time.

Parameters

settings (dict) – The retry settings.

Returns

The current backoff value.

Return type

float

get_retry_after(response)

Get the value of Retry-After in seconds.

Parameters

response (PipelineResponse) – The PipelineResponse object

Returns

Value of Retry-After in seconds.

Return type

float or None

increment(settings, response=None, error=None)

Increment the retry counters.

Parameters

• settings – The retry settings.

• response (PipelineResponse) – A pipeline response object.

• error – An error encountered during the request, or None if the response was received successfully.

Returns

Whether any retry attempt is available True if more retry attempts available, False otherwise

Return type

bool

is_exhausted(settings)

Checks if any retries left.

Parameters

settings (dict) – the retry settings

Returns

False if have more retries. True if retries exhausted.

Return type

bool

is_retry(settings, response)

Checks if method/status code is retryable.

Based on whitelists and control variables such as the number of total retries to allow, whether to respect the Retry-After header, whether this header is present, and whether the returned status code is on the list of status codes to be retried upon on the presence of the aforementioned header.

The behavior is: - If status_code < 400: don’t retry - Else if Retry-After present: retry - Else: retry based on the safe status code list ([408, 429, 500, 502, 503, 504])

Parameters

• settings (dict) – The retry settings.

• response (PipelineResponse) – The PipelineResponse object

Returns

True if method/status code is retryable. False if not retryable.

Return type

bool

classmethod no_retries()

Disable retries.

parse_retry_after(retry_after)

Helper to parse Retry-After and get value in seconds.

Parameters

retry_after (str) – Retry-After header

Return type

float

send(request)

Sends the PipelineRequest object to the next policy. Uses retry settings if necessary. Also enforces an absolute client-side timeout that spans multiple retry attempts.

Parameters

request (PipelineRequest) – The PipelineRequest object

Returns

Returns the PipelineResponse or raises error if maximum retries exceeded.

Return type

PipelineResponse

Raises

• AzureError – Maximum retries exceeded.

• CosmosClientTimeoutError – Specified timeout exceeded.

• ClientAuthenticationError – Authentication failed.

sleep(settings, transport, response=None)

Sleep between retry attempts.

This method will respect a server’s Retry-After response header and sleep the duration of the time requested. If that is not present, it will use an exponential backoff. By default, the backoff factor is 0 and this method will return immediately.

Parameters

• settings (dict) – The retry settings.

• transport – The HTTP transport type.

• response (PipelineResponse) – The PipelineResponse object.

update_context(context, retry_settings)

Updates retry history in pipeline context.

Parameters

• context (PipelineContext) – The pipeline context.

• retry_settings (dict) – The retry settings.

BACKOFF_MAX = 120

Submodules

azure.cosmos.auth module

Authorization helper functions in the Azure Cosmos database service.

azure.cosmos.auth.GetAuthorizationHeader(cosmos_client_connection, verb, path, resource_id_or_fullname, is_name_based, resource_type, headers)

Gets the authorization header.

Parameters

• cosmos_client (cosmos_client_connection.CosmosClient) –

• verb (str) –

• path (str) –

• resource_id_or_fullname (str) –

• resource_type (str) –

• headers (dict) –

Returns

The authorization headers.

Return type

dict

azure.cosmos.container module

Create, read, update and delete items in the Azure Cosmos DB SQL API service.

class azure.cosmos.container.ContainerProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, database_link: str, id: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific DB Container.

This class should not be instantiated directly. Instead, use the DatabaseProxy.get_container_client() method to get an existing container, or the Database.create_container() method to create a new container.

A container in an Azure Cosmos DB SQL API database is a collection of documents, each of which is represented as an Item.

Variables

• id (str) – ID (name) of the container

• session_token (str) – The session token for the container.

create_item(body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, indexing_directive: Optional[Any] = None, **kwargs: Any) → Dict[str, str]

Create an item in the container.

To update or replace an existing item, use the ContainerProxy.upsert_item() method.

Parameters

• body – A dict-like object representing the item to create.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

• indexing_directive – Indicate whether the document should be omitted from indexing.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the new item.

Raises

CosmosHttpResponseError – Item with the given ID already exists.

Return type

dict[str, Any]

delete_conflict(conflict: Union[str, Dict[str, Any]], partition_key: Any, **kwargs: Any) → None

Delete a specified conflict from the container.

If the conflict does not already exist in the container, an exception is raised.

Parameters

• conflict – The ID (name) or dict representing the conflict to be deleted.

• partition_key – Partition key for the conflict to delete.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The conflict wasn’t deleted successfully.

• CosmosResourceNotFoundError – The conflict does not exist in the container.

Return type

None

delete_item(item: Union[Dict[str, Any], str], partition_key: Any, populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → None

Delete the specified item from the container.

If the item does not already exist in the container, an exception is raised.

Parameters

• item – The ID (name) or dict representing item to be deleted.

• partition_key – Specifies the partition key value for the item.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The item wasn’t deleted successfully.

• CosmosResourceNotFoundError – The item does not exist in the container.

Return type

None

get_conflict(conflict: Union[str, Dict[str, Any]], partition_key: Any, **kwargs: Any) → Dict[str, str]

Get the conflict identified by conflict.

Parameters

• conflict – The ID (name) or dict representing the conflict to retrieve.

• partition_key – Partition key for the conflict to retrieve.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the retrieved conflict.

Raises

CosmosHttpResponseError – The given conflict couldn’t be retrieved.

Return type

dict[str, Any]

list_conflicts(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the conflicts in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

Iterable[dict[str, Any]]

query_conflicts(query: str, parameters: Optional[List[str]] = None, enable_cross_partition_query: Optional[bool] = None, partition_key: Optional[Any] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all conflicts matching a given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• enable_cross_partition_query – Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.

• partition_key – Specifies the partition key value for the item.

• max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

Iterable[dict[str, Any]]

query_items(query: str, parameters: Optional[List[str]] = None, partition_key: Optional[Any] = None, enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, enable_scan_in_query: Optional[bool] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all results matching the given query.

You can use any value for the container name in the FROM clause, but often the container name is used. In the examples below, the container name is “products,” and is aliased as “p” for easier referencing in the WHERE clause.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• partition_key – Specifies the partition key value for the item.

• enable_cross_partition_query – Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.

• max_item_count – Max number of items to be returned in the enumeration operation.

• enable_scan_in_query – Allow scan on the queries which couldn’t be served as indexing was opted out on the requested paths.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

Example:

Get all products that have not been discontinued:

import json

for item in container.query_items(
    query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
    enable_cross_partition_query=True,
):
    print(json.dumps(item, indent=True))

Parameterized query to get all products that have been discontinued:

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
    parameters=[dict(name="@model", value="DISCONTINUED")],
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

query_items_change_feed(partition_key_range_id: Optional[str] = None, is_start_from_beginning: bool = False, continuation: Optional[str] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Get a sorted list of items that were changed, in the order in which they were modified.

Parameters

• partition_key_range_id – ChangeFeed requests can be executed against specific partition key ranges. This is used to process the change feed in parallel across multiple consumers.

• is_start_from_beginning – Get whether change feed should start from beginning (true) or from current (false). By default it’s start from current (false).

• continuation – e_tag value to be used as continuation for reading change feed.

• max_item_count – Max number of items to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

read(populate_query_metrics: Optional[bool] = None, populate_partition_key_range_statistics: Optional[bool] = None, populate_quota_info: Optional[bool] = None, **kwargs: Any) → Dict[str, Any]

Read the container properties.

Parameters

• populate_query_metrics – Enable returning query metrics in response headers.

• populate_partition_key_range_statistics – Enable returning partition key range statistics in response headers.

• populate_quota_info – Enable returning collection storage quota information in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – Raised if the container couldn’t be retrieved. This includes if the container does not exist.

Returns

Dict representing the retrieved container.

Return type

dict[str, Any]

read_all_items(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the items in the container.

Parameters

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

Iterable[dict[str, Any]]

read_item(item: Union[str, Dict[str, Any]], partition_key: Any, populate_query_metrics: Optional[bool] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Get the item identified by item.

Parameters

• item – The ID (name) or dict representing item to retrieve.

• partition_key – Partition key for the item to retrieve.

• populate_query_metrics – Enable returning query metrics in response headers.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

Dict representing the item to be retrieved.

Raises

CosmosHttpResponseError – The given item couldn’t be retrieved.

Return type

dict[str, Any]

Example:

Get an item from the database and update one of its properties:

item = container.read_item("item2", partition_key="Widget")
item["productModel"] = "DISCONTINUED"
updated_item = container.upsert_item(item)

read_offer(**kwargs: Any) → azure.cosmos.offer.Offer

Read the Offer object for this container.

If no Offer already exists for the container, an exception is raised.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the container.

Raises

CosmosHttpResponseError – No offer exists for the container or the offer could not be retrieved.

Return type

Offer

replace_item(item: Union[str, Dict[str, Any]], body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Replaces the specified item if it exists in the container.

If the item does not already exist in the container, an exception is raised.

Parameters

• item – The ID (name) or dict representing item to be replaced.

• body – A dict-like object representing the item to replace.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the item after replace went through.

Raises

CosmosHttpResponseError – The replace failed or the item with given id does not exist.

Return type

dict[str, Any]

replace_throughput(throughput: int, **kwargs: Any) → azure.cosmos.offer.Offer

Replace the container’s throughput.

If no Offer already exists for the container, an exception is raised.

Parameters

throughput – The throughput to be set (an integer).

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the container, updated with new throughput.

Raises

CosmosHttpResponseError – No offer exists for the container or the offer could not be updated.

Return type

Offer

upsert_item(body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) → Dict[str, str]

Insert or update the specified item.

If the item already exists in the container, it is replaced. If the item does not already exist, it is inserted.

Parameters

• body – A dict-like object representing the item to update or insert.

• populate_query_metrics – Enable returning query metrics in response headers.

• pre_trigger_include – trigger id to be used as pre operation trigger.

• post_trigger_include – trigger id to be used as post operation trigger.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A dict representing the upserted item.

Raises

CosmosHttpResponseError – The given item could not be upserted.

Return type

dict[str, Any]

property is_system_key

property scripts

azure.cosmos.cosmos_client module

Create, read, and delete databases in the Azure Cosmos DB SQL API service.

class azure.cosmos.cosmos_client.CosmosClient(url: str, credential: Any, consistency_level: str = 'Session', **kwargs: Any)

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.

Parameters

• url (str) – The URL of the Cosmos DB account.

• credential (str or dict[str, str]) – 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 “Session”.

Keyword Arguments

• timeout (int) – An absolute timeout in seconds, for the combined HTTP request and response processing.

• request_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.

Example:

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)

Instantiate a new CosmosClient.

create_database(id: str, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, **kwargs: Any) → azure.cosmos.database.DatabaseProxy

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

Parameters

• id – ID (name) of the database to create.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

• offer_throughput (int) – The provisioned throughput for this offer.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A DatabaseProxy instance representing the new database.

Return type

DatabaseProxy

Raises

CosmosResourceExistsError – Database with the given ID already exists.

Example:

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(id: str, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, **kwargs: Any) → azure.cosmos.database.DatabaseProxy

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.

Parameters

• id – ID (name) of the database to read or create.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

• offer_throughput (int) – The provisioned throughput for this offer.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A DatabaseProxy instance representing the database.

Return type

DatabaseProxy

Raises

CosmosHttpResponseError – The database read or creation failed.

delete_database(database: Union[str, azure.cosmos.database.DatabaseProxy, Dict[str, Any]], populate_query_metrics: Optional[bool] = None, **kwargs: Any) → None

Delete the database with the given ID (name).

Parameters

• database (str or dict(str, str) or DatabaseProxy) – The ID (name), dict representing the properties or DatabaseProxy instance of the database to delete.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – If the database couldn’t be deleted.

Return type

None

classmethod from_connection_string(conn_str: str, credential: Optional[Any] = None, consistency_level: str = 'Session', **kwargs: Any) → azure.cosmos.cosmos_client.CosmosClient

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.

Parameters

• conn_str (str) – The connection string.

• credential (str or 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. The default value is “Session”.

get_database_account(**kwargs: Any) → azure.cosmos.documents.DatabaseAccount

Retrieve the database account information.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A DatabaseAccount instance representing the Cosmos DB Database Account.

Return type

DatabaseAccount

get_database_client(database: Union[str, azure.cosmos.database.DatabaseProxy, Dict[str, Any]]) → azure.cosmos.database.DatabaseProxy

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

Parameters

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

Returns

A DatabaseProxy instance representing the retrieved database.

Return type

DatabaseProxy

list_databases(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the databases in a Cosmos DB SQL database account.

Parameters

• max_item_count (int) – Max number of items to be returned in the enumeration operation.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of database properties (dicts).

Return type

Iterable[dict[str, str]]

query_databases(query: Optional[str] = None, parameters: Optional[List[str]] = None, enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Query the databases in a Cosmos DB SQL database account.

Parameters

• query (str) – The Azure Cosmos DB SQL query to execute.

• parameters (list[str]) – 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.

• max_item_count (int) – Max number of items to be returned in the enumeration operation.

• populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of database properties (dicts).

Return type

Iterable[dict[str, str]]

azure.cosmos.database module

Interact with databases in the Azure Cosmos DB SQL API service.

class azure.cosmos.database.DatabaseProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, id: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific database.

This class should not be instantiated directly. Instead use the CosmosClient.get_database_client() method.

A database contains one or more containers, each of which can contain items, stored procedures, triggers, and user-defined functions.

A database can also have associated users, each of which is configured with a set of permissions for accessing certain containers, stored procedures, triggers, user-defined functions, or items.

Variables

id – The ID (name) of the database.

An Azure Cosmos DB SQL API database has the following system-generated properties. These properties are read-only:

• _rid: The resource ID.

• _ts: When the resource was last updated. The value is a timestamp.

• _self: The unique addressable URI for the resource.

• _etag: The resource etag required for optimistic concurrency control.

• _colls: The addressable path of the collections resource.

• _users: The addressable path of the users resource.

Parameters

• client_connection (ClientSession) – Client from which this database was retrieved.

• id (str) – ID (name) of the database.

create_container(id: str, partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, unique_key_policy: Optional[Dict[str, Any]] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

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

If a container with the given ID already exists, a CosmosResourceExistsError is raised.

Parameters

• id – ID (name) of container to create.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• populate_query_metrics – Enable returning query metrics in response headers.

• offer_throughput – The provisioned throughput for this offer.

• unique_key_policy – The unique key policy to apply to the container.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A ContainerProxy instance representing the new container.

Raises

CosmosHttpResponseError – The container creation failed.

Return type

ContainerProxy

Example:

Create a container with default settings:

container_name = "products"
try:
    container = database.create_container(
        id=container_name, partition_key=PartitionKey(path="/productName")
    )
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(container_name)

Create a container with specific settings; in this case, a custom partition key:

customer_container_name = "customers"
try:
    customer_container = database.create_container(
        id=customer_container_name,
        partition_key=PartitionKey(path="/city"),
        default_ttl=200,
    )
except exceptions.CosmosResourceExistsError:
    customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, populate_query_metrics: Optional[bool] = None, offer_throughput: Optional[int] = None, unique_key_policy: Optional[Dict[str, Any]] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

Create a container if it does not exist already.

If the container already exists, the existing settings are returned. Note: it does not check or update the existing container settings or offer throughput if they differ from what was passed into the method.

Parameters

• id – ID (name) of container to read or create.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• populate_query_metrics – Enable returning query metrics in response headers.

• offer_throughput – The provisioned throughput for this offer.

• unique_key_policy – The unique key policy to apply to the container.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

A ContainerProxy instance representing the container.

Raises

CosmosHttpResponseError – The container read or creation failed.

Return type

ContainerProxy

create_user(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Create a new user in the container.

To update or replace an existing user, use the ContainerProxy.upsert_user() method.

Parameters

body – A dict-like object with an id key and value representing the user to be created. The user ID must be unique within the database, and consist of no more than 255 characters.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the new user.

Raises

CosmosHttpResponseError – If the given user couldn’t be created.

Return type

UserProxy

Example:

Create a database user:

try:
    database.create_user(dict(id="Walter Harp"))
except exceptions.CosmosResourceExistsError:
    print("A user with that ID already exists.")
except exceptions.CosmosHttpResponseError as failure:
    print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]], populate_query_metrics: Optional[bool] = None, **kwargs: Any) → None

Delete a container.

Parameters

• container – The ID (name) of the container to delete. You can either pass in the ID of the container to delete, a ContainerProxy instance or a dict representing the properties of the container.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – If the container couldn’t be deleted.

Return type

None

delete_user(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]], **kwargs: Any) → None

Delete the specified user from the container.

Parameters

user – The ID (name), dict representing the properties or UserProxy instance of the user to be deleted.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The user wasn’t deleted successfully.

• CosmosResourceNotFoundError – The user does not exist in the container.

Return type

None

get_container_client(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]]) → azure.cosmos.container.ContainerProxy

Get a ContainerProxy for a container with specified ID (name).

Parameters

container – The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.

Return type

ContainerProxy

Example:

Get an existing container, handling a failure if encountered:

database = client.get_database_client(database_name)
container = database.get_container_client(container_name)

get_user_client(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]]) → azure.cosmos.user.UserProxy

Get a UserProxy for a user with specified ID.

Parameters

user – The ID (name), dict representing the properties or UserProxy instance of the user to be retrieved.

Returns

A UserProxy instance representing the retrieved user.

Raises

CosmosHttpResponseError – If the given user couldn’t be retrieved.

Return type

UserProxy

list_containers(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the containers in the database.

Parameters

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of container properties (dicts).

Return type

Iterable[dict[str, Any]]

Example:

List all containers in the database:

database = client.get_database_client(database_name)
for container in database.list_containers():
    print("Container ID: {}".format(container.id))

list_users(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the users in the container.

Parameters

max_item_count – Max number of users to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of user properties (dicts).

Return type

Iterable[dict[str, Any]]

query_containers(query: Optional[str] = None, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List the properties for containers in the current database.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Returns

An Iterable of container properties (dicts).

Return type

Iterable[dict[str, Any]]

query_users(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all users matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of users to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of user properties (dicts).

Return type

Iterable[str, Any]

read(populate_query_metrics: Optional[bool] = None, **kwargs: Any) → Dict[str, Any]

Read the database properties.

Parameters

populate_query_metrics (bool) – Enable returning query metrics in response headers.

Keyword Arguments

• 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) – A callable invoked with the response metadata.

Return type

Dict[Str, Any]

Raises

CosmosHttpResponseError – If the given database couldn’t be retrieved.

read_offer(**kwargs: Any) → azure.cosmos.offer.Offer

Read the Offer object for this database.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the database.

Raises

CosmosHttpResponseError – If no offer exists for the database or if the offer could not be retrieved.

Return type

Offer

replace_container(container: Union[str, azure.cosmos.container.ContainerProxy, Dict[str, Any]], partition_key: Any, indexing_policy: Optional[Dict[str, Any]] = None, default_ttl: Optional[int] = None, conflict_resolution_policy: Optional[Dict[str, Any]] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) → azure.cosmos.container.ContainerProxy

Reset the properties of the container.

Property changes are persisted immediately. Any properties not specified will be reset to their default values.

Parameters

• container – The ID (name), dict representing the properties or ContainerProxy instance of the container to be replaced.

• partition_key – The partition key to use for the container.

• indexing_policy – The indexing policy to apply to the container.

• default_ttl – Default time to live (TTL) for items in the container. If unspecified, items do not expire.

• conflict_resolution_policy – The conflict resolution policy to apply to the container.

• populate_query_metrics – Enable returning query metrics in response headers.

Keyword Arguments

• 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.

• initial_headers (dict[str,str]) – Initial headers to be sent as part of the request.

• response_hook (Callable) – A callable invoked with the response metadata.

Raises

CosmosHttpResponseError – Raised if the container couldn’t be replaced. This includes if the container with given id does not exist.

Returns

A ContainerProxy instance representing the container after replace completed.

Return type

ContainerProxy

Example:

Reset the TTL property on a container, and display the updated properties:

# Set the TTL on the container to 3600 seconds (one hour)
database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

# Display the new TTL setting for the container
container_props = database.get_container_client(container_name).read()
print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput(throughput: Optional[int], **kwargs: Any) → azure.cosmos.offer.Offer

Replace the database-level throughput.

Parameters

throughput – The throughput to be set (an integer).

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

Offer for the database, updated with new throughput.

Raises

CosmosHttpResponseError – If no offer exists for the database or if the offer could not be updated.

Return type

Offer

replace_user(user: Union[str, azure.cosmos.user.UserProxy, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Replaces the specified user if it exists in the container.

Parameters

• user – The ID (name), dict representing the properties or UserProxy instance of the user to be replaced.

• body – A dict-like object representing the user to replace.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the user after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the user with given ID does not exist.

Return type

UserProxy

upsert_user(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.user.UserProxy

Insert or update the specified user.

If the user already exists in the container, it is replaced. If the user does not already exist, it is inserted.

Parameters

body – A dict-like object representing the user to update or insert.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A UserProxy instance representing the upserted user.

Raises

CosmosHttpResponseError – If the given user could not be upserted.

Return type

UserProxy

azure.cosmos.diagnostics module

Diagnostic tools for Azure Cosmos database service operations.

class azure.cosmos.diagnostics.RecordDiagnostics

Record Response headers from Cosmos read operations.

The full response headers are stored in the headers property.

Examples

>>> rh = RecordDiagnostics()

>>> col = b.create_container(
...     id="some_container",
...     partition_key=PartitionKey(path='/id', kind='Hash'),
...     response_hook=rh)

>>> rh.headers['x-ms-activity-id']
'6243eeed-f06a-413d-b913-dcf8122d0642'

clear()

property body

property headers

property request_charge

azure.cosmos.documents module

Classes and enums for documents in the Azure Cosmos database service.

class azure.cosmos.documents.ConnectionMode

Represents the connection mode to be used by the client.

Variables

Gateway (int) – Use the Azure Cosmos gateway to route all requests. The gateway proxies requests to the right data partition.

Gateway = 0

class azure.cosmos.documents.ConnectionPolicy

Represents the Connection policy assocated with a CosmosClientConnection.

Variables

• RequestTimeout (int) – Gets or sets the request timeout (time to wait for a response from a network peer).

• ConnectionMode (documents.ConnectionMode) – Gets or sets the connection mode used in the client. (Currently only Gateway is supported.)

• SSLConfiguration (documents.SSLConfiguration) – Gets or sets the SSL configuration.

• ProxyConfiguration (documents.ProxyConfiguration) – Gets or sets the proxy configuration.

• EnableEndpointDiscovery (boolean) – Gets or sets endpoint discovery flag for geo-replicated database accounts. When EnableEndpointDiscovery is true, the client will automatically discover the current write and read locations and direct the requests to the correct location taking into consideration of the user’s preference(if provided) as PreferredLocations.

• PreferredLocations (list) – Gets or sets the preferred locations for geo-replicated database accounts. When EnableEndpointDiscovery is true and PreferredLocations is non-empty, the client will use this list to evaluate the final location, taking into consideration the order specified in PreferredLocations. The locations in this list are specified as the names of the azure Cosmos locations like, ‘West US’, ‘East US’, ‘Central India’ and so on.

• RetryOptions (RetryOptions) – Gets or sets the retry options to be applied to all requests when retrying.

• DisableSSLVerification (boolean) –

  Flag to disable SSL verification for the requests. SSL verification is enabled by default.

  This is intended to be used only when targeting emulator endpoint to avoid failing your requests with SSL related error.

  DO NOT set this when targeting production endpoints.

• UseMultipleWriteLocations (boolean) – Flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos database service.

• ConnectionRetryConfiguration (int or azure.cosmos.ConnectionRetryPolicy or urllib3.util.retry) – Retry Configuration to be used for connection retries.

class azure.cosmos.documents.ConsistencyLevel

Represents the consistency levels supported for Azure Cosmos client operations.

The requested ConsistencyLevel must match or be weaker than that provisioned for the database account. Consistency levels.

Consistency levels by order of strength are Strong, BoundedStaleness, Session, ConsistentPrefix and Eventual.

Variables

• ConsistencyLevel.Strong (str) – Strong Consistency guarantees that read operations always return the value that was last written.

• ConsistencyLevel.BoundedStaleness (str) – Bounded Staleness guarantees that reads are not too out-of-date. This can be configured based on number of operations (MaxStalenessPrefix) or time (MaxStalenessIntervalInSeconds).

• ConsistencyLevel.Session (str) – Session Consistency guarantees monotonic reads (you never read old data, then new, then old again), monotonic writes (writes are ordered) and read your writes (your writes are immediately visible to your reads) within any single session.

• ConsistencyLevel.Eventual (str) – Eventual Consistency guarantees that reads will return a subset of writes. All writes will be eventually be available for reads.

• ConsistencyLevel.ConsistentPrefix (str) – ConsistentPrefix Consistency guarantees that reads will return some prefix of all writes with no gaps. All writes will be eventually be available for reads.

BoundedStaleness = 'BoundedStaleness'

ConsistentPrefix = 'ConsistentPrefix'

Eventual = 'Eventual'

Session = 'Session'

Strong = 'Strong'

class azure.cosmos.documents.DataType

Specifies the data type of index specs.

Variables

• Number (str) – Represents a numeric data type.

• String (str) – Represents a string data type.

• Point (str) – Represents a point data type.

• LineString (str) – Represents a line string data type.

• Polygon (str) – Represents a polygon data type.

• MultiPolygon (str) – Represents a multi-polygon data type.

LineString = 'LineString'

MultiPolygon = 'MultiPolygon'

Number = 'Number'

Point = 'Point'

Polygon = 'Polygon'

String = 'String'

class azure.cosmos.documents.DatabaseAccount

Database account.

A DatabaseAccount is the container for databases.

Variables

• DatabaseLink (str) – The self-link for Databases in the databaseAccount.

• MediaLink (str) – The self-link for Media in the databaseAccount.

• MaxMediaStorageUsageInMB (int) – Attachment content (media) storage quota in MBs (Retrieved from gateway).

• CurrentMediaStorageUsageInMB (int) – Current attachment content (media) usage in MBs (Retrieved from gateway). Value is returned from cached information updated periodically and is not guaranteed to be real time.

• ConsistencyPolicy (dict) – UserConsistencyPolicy settings.

• ConsistencyPolicy['defaultConsistencyLevel'] (dict) – The default consistency level.

• ConsistencyPolicy['maxStalenessPrefix'] (int) – In bounded staleness consistency, the maximum allowed staleness in terms difference in sequence numbers (aka version).

• ConsistencyPolicy['maxStalenessIntervalInSeconds'] (int) – In bounded staleness consistency, the maximum allowed staleness in terms time interval.

• EnableMultipleWritableLocations (boolean) – Flag on the azure Cosmos account that indicates if writes can take place in multiple locations.

property ReadableLocations

The list of readable locations for a geo-replicated database account.

property WritableLocations

The list of writable locations for a geo-replicated database account.

class azure.cosmos.documents.IndexKind

Specifies the index kind of index specs.

Variables

• IndexKind.Hash (str) – The index entries are hashed to serve point look up queries. Can be used to serve queries like: SELECT * FROM docs d WHERE d.prop = 5

• IndexKind.Range (str) – The index entries are ordered. Range indexes are optimized for inequality predicate queries with efficient range scans. Can be used to serve queries like: SELECT * FROM docs d WHERE d.prop > 5

Hash = 'Hash'

Range = 'Range'

class azure.cosmos.documents.IndexingDirective

Specifies whether or not the resource is to be indexed.

Variables

• Default (int) – Use any pre-defined/pre-configured defaults.

• Exclude (int) – Index the resource.

• Include (int) – Do not index the resource.

Default = 0

Exclude = 1

Include = 2

class azure.cosmos.documents.IndexingMode

Specifies the supported indexing modes.

Variables

• Consistent (str) –

  Index is updated synchronously with a create or update operation. With consistent indexing, query behavior is the same as the default consistency level for the collection.

  The index is always kept up to date with the data.

• Lazy (str) –

  Index is updated asynchronously with respect to a create or update operation.

  With lazy indexing, queries are eventually consistent. The index is updated when the collection is idle.

• NoIndex (str) –

  No index is provided.

  Setting IndexingMode to “None” drops the index. Use this if you don’t want to maintain the index for a document collection, to save the storage cost or improve the write throughput. Your queries will degenerate to scans of the entire collection.

Consistent = 'consistent'

Lazy = 'lazy'

NoIndex = 'none'

class azure.cosmos.documents.PartitionKind

Specifies the kind of partitioning to be applied.

Variables

PartitionKind.Hash (str) – The partition key definition path is hashed.

Hash = 'Hash'

class azure.cosmos.documents.PermissionMode

Enumeration specifying applicability of a permission.

Variables

• PermissionMode.NoneMode (str) – None.

• PermissionMode.Read (str) – Permission applicable for read operations only.

• PermissionMode.All (str) – Permission applicable for all operations.

All = 'all'

NoneMode = 'none'

Read = 'read'

class azure.cosmos.documents.ProxyConfiguration

Configuration for a proxy.

Variables

• Host (str) – The host address of the proxy.

• Port (int) – The port number of the proxy.

class azure.cosmos.documents.SSLConfiguration

Configuration for SSL connections.

See https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification for more information.

Variables

• SSLKeyFIle (str) – The path of the key file for ssl connection.

• SSLCertFile (str) – The path of the cert file for ssl connection.

• SSLCaCerts (str) – The path of the CA_BUNDLE file with certificates of trusted CAs.

class azure.cosmos.documents.TriggerOperation

Specifies the operations on which a trigger should be executed.

Variables

• TriggerOperation.All (str) – All operations.

• TriggerOperation.Create (str) – Create operations only.

• TriggerOperation.Update (str) – Update operations only.

• TriggerOperation.Delete (str) – Delete operations only.

• TriggerOperation.Replace (str) – Replace operations only.

All = 'all'

Create = 'create'

Delete = 'delete'

Replace = 'replace'

Update = 'update'

class azure.cosmos.documents.TriggerType

Specifies the type of a trigger.

Variables

• TriggerType.Pre (str) – Trigger should be executed before the associated operation(s).

• TriggerType.Post (str) – Trigger should be executed after the associated operation(s).

Post = 'post'

Pre = 'pre'

azure.cosmos.errors module

Service-specific Exceptions in the Azure Cosmos database service.

Warning

This module is DEPRECATED. Use azure.cosmos.exceptions instead.

azure.cosmos.exceptions module

Service-specific Exceptions in the Azure Cosmos database service.

exception azure.cosmos.exceptions.CosmosAccessConditionFailedError(status_code=None, message=None, response=None, **kwargs)

An HTTP error response with status code 412.

Parameters

• status_code (int) – HTTP response code.

• message (str) – Error message.

raise_with_traceback()

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception azure.cosmos.exceptions.CosmosClientTimeoutError(**kwargs)

An operation failed to complete within the specified timeout.

raise_with_traceback()

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception azure.cosmos.exceptions.CosmosHttpResponseError(status_code=None, message=None, response=None, **kwargs)

An HTTP request to the Azure Cosmos database service has failed.

Parameters

• status_code (int) – HTTP response code.

• message (str) – Error message.

raise_with_traceback()

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception azure.cosmos.exceptions.CosmosResourceExistsError(status_code=None, message=None, response=None, **kwargs)

An HTTP error response with status code 409.

Parameters

• status_code (int) – HTTP response code.

• message (str) – Error message.

raise_with_traceback()

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

exception azure.cosmos.exceptions.CosmosResourceNotFoundError(status_code=None, message=None, response=None, **kwargs)

An HTTP error response with status code 404.

Parameters

• status_code (int) – HTTP response code.

• message (str) – Error message.

raise_with_traceback()

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args

azure.cosmos.http_constants module

HTTP Constants in the Azure Cosmos database service.

class azure.cosmos.http_constants.CookieHeaders

Constants of cookie headers.

SessionToken = 'x-ms-session-token'

class azure.cosmos.http_constants.Delimiters

Constants of delimiters.

ClientContinuationDelimiter = '!!'

ClientContinuationFormat = '{0}!!{1}'

class azure.cosmos.http_constants.HttpContextProperties

Constants of http context properties.

SubscriptionId = 'SubscriptionId'

class azure.cosmos.http_constants.HttpHeaderPreferenceTokens

Constants of http header preference tokens.

PreferUnfilteredQueryResponse = 'PreferUnfilteredQueryResponse'

class azure.cosmos.http_constants.HttpHeaders

Constants of http headers.

AIM = 'A-IM'

Accept = 'Accept'

AcceptCharset = 'Accept-Charset'

AcceptEncoding = 'Accept-Encoding'

AcceptLanguage = 'Accept-Language'

AcceptRanges = 'Accept-Ranges'

AccessControlAllowHeaders = 'Access-Control-Allow-Headers'

AccessControlAllowOrigin = 'Access-Control-Allow-Origin'

ActivityId = 'x-ms-activity-id'

AllowTentativeWrites = 'x-ms-cosmos-allow-tentative-writes'

AlternateContentPath = 'x-ms-alt-content-path'

Authorization = 'authorization'

CacheControl = 'Cache-Control'

CharacterSet = 'CharacterSet'

CollectionCurrentUsageInMb = 'x-ms-collection-usage-mb'

CollectionPartitionInfo = 'x-ms-collection-partition-info'

CollectionQuotaInMb = 'x-ms-collection-quota-mb'

CollectionServiceInfo = 'x-ms-collection-service-info'

ConsistencyLevel = 'x-ms-consistency-level'

ContentEncoding = 'Content-Encoding'

ContentLanguage = 'Content-Language'

ContentLength = 'Content-Length'

ContentLocation = 'Content-Location'

ContentMd5 = 'Content-Md5'

ContentRange = 'Content-Range'

ContentType = 'Content-Type'

Continuation = 'x-ms-continuation'

CurrentEntityCount = 'x-ms-root-entity-current-count'

CurrentMediaStorageUsageInMB = 'x-ms-media-storage-usage-mb'

DisableRUPerMinuteUsage = 'x-ms-documentdb-disable-ru-per-minute-usage'

ETag = 'etag'

EmitVerboseTracesInQuery = 'x-ms-documentdb-query-emit-traces'

EnableCrossPartitionQuery = 'x-ms-documentdb-query-enablecrosspartition'

EnableScanInQuery = 'x-ms-documentdb-query-enable-scan'

EnableScriptLogging = 'x-ms-documentdb-script-enable-logging'

ForceRefresh = 'x-ms-force-refresh'

FullUpgrade = 'x-ms-force-full-upgrade'

Host = 'Host'

HttpDate = 'date'

IfMatch = 'If-Match'

IfModified_since = 'If-Modified-Since'

IfNoneMatch = 'If-None-Match'

IfRange = 'If-Range'

IfUnmodifiedSince = 'If-Unmodified-Since'

IgnoreInProgressUpgrade = 'x-ms-ignore-inprogress-upgrade'

IncrementalFeedHeaderValue = 'Incremental feed'

IndexTransformationProgress = 'x-ms-documentdb-collection-index-transformation-progress'

IndexingDirective = 'x-ms-indexing-directive'

IsCanary = 'x-ms-iscanary'

IsContinuationExpected = 'x-ms-documentdb-query-iscontinuationexpected'

IsFeedUnfiltered = 'x-ms-is-feed-unfiltered'

IsQuery = 'x-ms-documentdb-isquery'

IsQueryPlanRequest = 'x-ms-cosmos-is-query-plan-request'

IsRUPerMinuteUsed = 'x-ms-documentdb-is-ru-per-minute-used'

IsUpsert = 'x-ms-documentdb-is-upsert'

ItemCount = 'x-ms-item-count'

KeepAlive = 'Keep-Alive'

KeyValueEncodingFormat = 'application/x-www-form-urlencoded'

LastModified = 'Last-Modified'

LastStateChangeUtc = 'x-ms-last-state-change-utc'

LazyIndexingProgress = 'x-ms-documentdb-collection-lazy-indexing-progress'

Location = 'Location'

MaxEntityCount = 'x-ms-root-entity-max-count'

MaxForwards = 'Max-Forwards'

MaxMediaStorageUsageInMB = 'x-ms-max-media-storage-usage-mb'

MethodOverride = 'X-HTTP-Method'

NewResourceId = 'x-ms-new-resource-id'

OcpResourceProviderRegisteredUri = 'ocp-resourceprovider-registered-uri'

OfferIsRUPerMinuteThroughputEnabled = 'x-ms-offer-is-ru-per-minute-throughput-enabled'

OfferThroughput = 'x-ms-offer-throughput'

OfferType = 'x-ms-offer-type'

OnlyUpgradeNonSystemApplications = 'x-ms-only-upgrade-non-system-applications'

OnlyUpgradeSystemApplications = 'x-ms-only-upgrade-system-applications'

Origin = 'Origin'

PageSize = 'x-ms-max-item-count'

PartitionKey = 'x-ms-documentdb-partitionkey'

PartitionKeyRangeID = 'x-ms-documentdb-partitionkeyrangeid'

PopulatePartitionKeyRangeStatistics = 'x-ms-documentdb-populatepartitionstatistics'

PopulateQueryMetrics = 'x-ms-documentdb-populatequerymetrics'

PopulateQuotaInfo = 'x-ms-documentdb-populatequotainfo'

PostTriggerExclude = 'x-ms-documentdb-post-trigger-exclude'

PostTriggerInclude = 'x-ms-documentdb-post-trigger-include'

PreTriggerExclude = 'x-ms-documentdb-pre-trigger-exclude'

PreTriggerInclude = 'x-ms-documentdb-pre-trigger-include'

Prefer = 'Prefer'

ProxyAuthenticate = 'Proxy-Authenticate'

ProxyAuthorization = 'Proxy-Authorization'

Query = 'x-ms-documentdb-query'

QueryVersion = 'x-ms-cosmos-query-version'

Referer = 'referer'

RequestCharge = 'x-ms-request-charge'

RequestId = 'x-ms-request-id'

ResourceTokenExpiry = 'x-ms-documentdb-expiry-seconds'

RetryAfter = 'Retry-After'

RetryAfterInMilliseconds = 'x-ms-retry-after-ms'

ScriptLogResults = 'x-ms-documentdb-script-log-results'

SessionToken = 'x-ms-session-token'

SetCookie = 'Set-Cookie'

SimpleToken = 'SWT'

Slug = 'Slug'

SubStatus = 'x-ms-substatus'

SupportedQueryFeatures = 'x-ms-cosmos-supported-query-features'

ThrottleRetryCount = 'x-ms-throttle-retry-count'

ThrottleRetryWaitTimeInMs = 'x-ms-throttle-retry-wait-time-ms'

TransferEncoding = 'Transfer-Encoding'

UpgradeFabricRingCodeAndConfig = 'x-ms-upgrade-fabric-code-config'

UpgradeVerificationKind = 'x-ms-upgrade-verification-kind'

UseMasterCollectionResolver = 'x-ms-use-master-collection-resolver'

UserAgent = 'User-Agent'

Version = 'x-ms-version'

WrapAssertion = 'wrap_assertion'

WrapAssertionFormat = 'wrap_assertion_format'

WrapScope = 'wrap_scope'

WwwAuthenticate = 'Www-Authenticate'

XDate = 'x-ms-date'

class azure.cosmos.http_constants.HttpListenerErrorCodes

Constants of http listener error codes.

ERROR_CONNECTION_INVALID = 1229

ERROR_OPERATION_ABORTED = 995

class azure.cosmos.http_constants.HttpMethods

Constants of http methods.

Delete = 'DELETE'

Get = 'GET'

Head = 'HEAD'

Options = 'OPTIONS'

Post = 'POST'

Put = 'PUT'

class azure.cosmos.http_constants.HttpStatusDescriptions

Constants of http status descriptions.

Accepted = 'Accepted'

BadGateway = 'Bad Gateway'

BadRequest = 'Bad Request'

Conflict = 'Conflict'

Created = 'Created'

Forbidden = 'Forbidden'

GatewayTimeout = 'Gateway timed out'

Gone = 'Gone'

InternalServerError = 'Internal Server Error'

LengthRequired = 'Length Required'

MethodNotAllowed = 'MethodNotAllowed'

NoContent = 'No Content'

NotAcceptable = 'Not Acceptable'

NotFound = 'Not Found'

NotModified = 'Not Modified'

OK = 'Ok'

PreconditionFailed = 'Precondition Failed'

RequestEntityTooLarge = 'Request Entity Too Large'

RequestTimeout = 'Request timed out'

RetryWith = 'Retry the request'

ServiceUnavailable = 'Service Unavailable'

TooManyRequests = 'Too Many Requests'

Unauthorized = 'Unauthorized'

UnsupportedMediaType = 'Unsupported Media Type'

class azure.cosmos.http_constants.QueryStrings

Constants of query strings.

ContentView = 'contentview'

Filter = '$filter'

GenerateId = '$generateFor'

GenerateIdBatchSize = '$batchSize'

Generic = 'generic'

GetChildResourcePartitions = '$getChildResourcePartitions'

Query = 'query'

RootIndex = '$rootIndex'

SQLQueryType = 'sql'

Url = '$resolveFor'

class azure.cosmos.http_constants.ResourceType

Types of resources in Azure Cosmos

static IsCollectionChild(resourceType)

Attachment = 'attachments'

Collection = 'colls'

Conflict = 'conflicts'

Database = 'dbs'

DatabaseAccount = 'databaseaccount'

Document = 'docs'

Offer = 'offers'

PartitionKeyRange = 'pkranges'

Permission = 'permissions'

Schema = 'schemas'

StoredProcedure = 'sprocs'

Topology = 'topology'

Trigger = 'triggers'

User = 'users'

UserDefinedFunction = 'udfs'

class azure.cosmos.http_constants.StatusCodes

HTTP status codes returned by the REST operations

ACCEPTED = 202

BAD_REQUEST = 400

CONFLICT = 409

CREATED = 201

FORBIDDEN = 403

GONE = 410

INTERNAL_SERVER_ERROR = 500

METHOD_NOT_ALLOWED = 405

NOT_FOUND = 404

NOT_MODIFIED = 304

NO_CONTENT = 204

OK = 200

OPERATION_CANCELLED = 1201

OPERATION_PAUSED = 1200

PRECONDITION_FAILED = 412

REQUEST_ENTITY_TOO_LARGE = 413

REQUEST_TIMEOUT = 408

RETRY_WITH = 449

SERVICE_UNAVAILABLE = 503

TOO_MANY_REQUESTS = 429

UNAUTHORIZED = 401

class azure.cosmos.http_constants.SubStatusCodes

Sub status codes returned by the REST operations specifying the details of the operation

COMPLETING_PARTITION_MIGRATION = 1008

COMPLETING_SPLIT = 1007

CONFLICT_WITH_CONTROL_PLANE = 1006

CROSS_PARTITION_QUERY_NOT_SERVABLE = 1004

DATABASE_ACCOUNT_NOT_FOUND = 1008

INSUFFICIENT_BINDABLE_PARTITIONS = 1007

NAME_CACHE_IS_STALE = 1000

OWNER_RESOURCE_NOT_FOUND = 1003

PARTITION_KEY_MISMATCH = 1001

PARTITION_KEY_RANGE_GONE = 1002

PROVISION_LIMIT_REACHED = 1005

READ_SESSION_NOTAVAILABLE = 1002

REDUNDANT_COLLECTION_PUT = 1009

SHARED_THROUGHPUT_DATABASE_QUOTA_EXCEEDED = 1010

SHARED_THROUGHPUT_OFFER_GROW_NOT_NEEDED = 1011

UNKNOWN = 0

WRITE_FORBIDDEN = 3

class azure.cosmos.http_constants.Versions

Constants of versions.

CurrentVersion = '2018-12-31'

QueryVersion = '1.0'

SDKName = 'azure-cosmos'

azure.cosmos.offer module

Create offers in the Azure Cosmos DB SQL API service.

class azure.cosmos.offer.Offer(offer_throughput: int, properties: Optional[Dict[str, Any]] = None)

Represents a offer in an Azure Cosmos DB SQL API container.

To read and update offers use the associated methods on the Container.

azure.cosmos.partition_key module

Create partition keys in the Azure Cosmos DB SQL API service.

class azure.cosmos.partition_key.NonePartitionKeyValue

Represents None value for partitionKey when it’s missing in a container.

class azure.cosmos.partition_key.PartitionKey(path, kind='Hash', version=2)

Key used to partition a container into logical partitions.

See https://docs.microsoft.com/azure/cosmos-db/partitioning-overview#choose-partitionkey for information on how to choose partition keys.

Variables

• path – The path of the partition key

• kind – What kind of partition key is being defined (default: “Hash”)

• version – The version of the partition key (default: 2)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys()

Returns a new dict with keys from iterable and values equal to value.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D’s items

keys() → a set-like object providing a view on D’s keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D’s values

property kind

property path

property version

azure.cosmos.permission module

Create permissions in the Azure Cosmos DB SQL API service.

class azure.cosmos.permission.Permission(id: str, user_link: str, permission_mode: Union[str, azure.cosmos.documents.PermissionMode], resource_link: str, properties: Dict[str, Any])

Represents a Permission object in the Azure Cosmos DB SQL API service.

azure.cosmos.scripts module

Create, read, update and delete and execute scripts in the Azure Cosmos DB SQL API service.

class azure.cosmos.scripts.ScriptType

StoredProcedure = 'sprocs'

Trigger = 'triggers'

UserDefinedFunction = 'udfs'

class azure.cosmos.scripts.ScriptsProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, container_link: str, is_system_key: bool)

An interface to interact with stored procedures.

This class should not be instantiated directly. Instead, use the ContainerProxy.scripts() attribute.

create_stored_procedure(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a new stored procedure in the container.

To replace an existing sproc, use the Container.scripts.replace_stored_procedure() method.

Parameters

body – A dict-like object representing the sproc to create.

Returns

A dict representing the new stored procedure.

Raises

CosmosHttpResponseError – If the given stored procedure couldn’t be created.

Return type

dict[str, Any]

create_trigger(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a trigger in the container.

To replace an existing trigger, use the ContainerProxy.scripts.replace_trigger() method.

Parameters

body – A dict-like object representing the trigger to create.

Returns

A dict representing the new trigger.

Raises

CosmosHttpResponseError – If the given trigger couldn’t be created.

Return type

dict[str, Any]

create_user_defined_function(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Create a user-defined function in the container.

To replace an existing UDF, use the ContainerProxy.scripts.replace_user_defined_function() method.

Parameters

body – A dict-like object representing the udf to create.

Returns

A dict representing the new user-defined function.

Raises

CosmosHttpResponseError – If the user-defined function couldn’t be created.

Return type

dict[str, Any]

delete_stored_procedure(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified stored procedure from the container.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

sproc – The ID (name) or dict representing stored procedure to be deleted.

Raises

• CosmosHttpResponseError – The sproc wasn’t deleted successfully.

• CosmosResourceNotFoundError – The sproc does not exist in the container.

Return type

None

delete_trigger(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified trigger from the container.

If the trigger does not already exist in the container, an exception is raised.

Parameters

trigger – The ID (name) or dict representing trigger to be deleted.

Raises

• CosmosHttpResponseError – The trigger wasn’t deleted successfully.

• CosmosResourceNotFoundError – The trigger does not exist in the container.

Return type

None

delete_user_defined_function(udf: Union[str, Dict[str, Any]], **kwargs: Any) → None

Delete a specified user-defined function from the container.

If the UDF does not already exist in the container, an exception is raised.

Parameters

udf – The ID (name) or dict representing udf to be deleted.

Raises

• CosmosHttpResponseError – The udf wasn’t deleted successfully.

• CosmosResourceNotFoundError – The UDF does not exist in the container.

Return type

None

execute_stored_procedure(sproc: Union[str, Dict[str, Any]], partition_key: Optional[str] = None, params: Optional[List[Any]] = None, enable_script_logging: Optional[bool] = None, **kwargs: Any) → Any

Execute a specified stored procedure.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

• sproc – The ID (name) or dict representing stored procedure to be executed.

• partition_key – Specifies the partition key to indicate which partition the sproc should execute on.

• params – List of parameters to be passed to the stored procedure to be executed.

• enable_script_logging (bool) – Enables or disables script logging for the current request.

Returns

Result of the executed stored procedure for the given parameters.

Raises

CosmosHttpResponseError – If the stored procedure execution failed or if the stored procedure with given id does not exists in the container.

Return type

dict[str, Any]

get_stored_procedure(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get the stored procedure identified by id.

Parameters

sproc – The ID (name) or dict representing stored procedure to retrieve.

Returns

A dict representing the retrieved stored procedure.

Raises

CosmosHttpResponseError – If the given stored procedure couldn’t be retrieved.

Return type

dict[str, Any]

get_trigger(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get a trigger identified by id.

Parameters

trigger – The ID (name) or dict representing trigger to retrieve.

Returns

A dict representing the retrieved trigger.

Raises

CosmosHttpResponseError – If the given trigger couldn’t be retrieved.

Return type

dict[str, Any]

get_user_defined_function(udf: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any]

Get a user-defined functions identified by id.

Parameters

udf – The ID (name) or dict representing udf to retrieve.

Returns

A dict representing the retrieved user-defined function.

Raises

CosmosHttpResponseError – If the user-defined function couldn’t be retrieved.

Return type

Iterable[dict[str, Any]]

list_stored_procedures(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all stored procedures in the container.

Parameters

max_item_count (int) – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of stored procedures (dicts).

Return type

Iterable[dict[str, Any]]

list_triggers(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all triggers in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of triggers (dicts).

Return type

Iterable[dict[str, Any]]

list_user_defined_functions(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all the user-defined functions in the container.

Parameters

max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of user-defined functions (dicts).

Return type

Iterable[dict[str, Any]]

query_stored_procedures(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all stored procedures matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of stored procedures (dicts).

Return type

Iterable[dict[str, Any]]

query_triggers(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all triggers matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of triggers (dicts).

Return type

Iterable[dict[str, Any]]

query_user_defined_functions(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return user-defined functions matching a given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of items to be returned in the enumeration operation.

Returns

An Iterable of user-defined functions (dicts).

Return type

Iterable[dict[str, Any]]

replace_stored_procedure(sproc: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified stored procedure in the container.

If the stored procedure does not already exist in the container, an exception is raised.

Parameters

• sproc – The ID (name) or dict representing stored procedure to be replaced.

• body – A dict-like object representing the sproc to replace.

Returns

A dict representing the stored procedure after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the stored procedure with given id does not exist.

Return type

dict[str, Any]

replace_trigger(trigger: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified tigger in the container.

If the trigger does not already exist in the container, an exception is raised.

Parameters

• trigger – The ID (name) or dict representing trigger to be replaced.

• body – A dict-like object representing the trigger to replace.

Returns

A dict representing the trigger after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the trigger with given id does not exist.

Return type

dict[str, Any]

replace_user_defined_function(udf: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any]

Replace a specified user-defined function in the container.

If the UDF does not already exist in the container, an exception is raised.

Parameters

• udf – The ID (name) or dict representing udf to be replaced.

• body – A dict-like object representing the udf to replace.

Returns

A dict representing the user-defined function after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the user-defined function with the given id does not exist.

Return type

dict[str, Any]

azure.cosmos.user module

Create, read, update and delete users in the Azure Cosmos DB SQL API service.

class azure.cosmos.user.UserProxy(client_connection: azure.cosmos._cosmos_client_connection.CosmosClientConnection, id: str, database_link: str, properties: Optional[Dict[str, Any]] = None)

An interface to interact with a specific user.

This class should not be instantiated directly. Instead, use the DatabaseProxy.get_user_client() method.

create_permission(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Create a permission for the user.

To update or replace an existing permision, use the UserProxy.upsert_permission() method.

Parameters

body – A dict-like object representing the permission to create.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the new permission.

Raises

CosmosHttpResponseError – If the given permission couldn’t be created.

Return type

dict[str, Any]

delete_permission(permission: str, **kwargs: Any) → None

Delete the specified permission from the user.

If the permission does not already exist, an exception is raised.

Parameters

permission – The ID (name), dict representing the properties or Permission instance of the permission to be replaced.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Raises

• CosmosHttpResponseError – The permission wasn’t deleted successfully.

• CosmosResourceNotFoundError – The permission does not exist for the user.

Return type

None

get_permission(permission: str, **kwargs: Any) → azure.cosmos.permission.Permission

Get the permission identified by id.

Parameters

permission – The ID (name), dict representing the properties or Permission instance of the permission to be retrieved.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the retrieved permission.

Raises

CosmosHttpResponseError – If the given permission couldn’t be retrieved.

Return type

dict[str, Any]

list_permissions(max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

List all permission for the user.

Parameters

max_item_count – Max number of permissions to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of permissions (dicts).

Return type

Iterable[dict[str, Any]]

query_permissions(query: str, parameters: Optional[List[str]] = None, max_item_count: Optional[int] = None, **kwargs: Any) → Iterable[Dict[str, Any]]

Return all permissions matching the given query.

Parameters

• query – The Azure Cosmos DB SQL query to execute.

• parameters – Optional array of parameters to the query. Ignored if no query is provided.

• max_item_count – Max number of permissions to be returned in the enumeration operation.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

An Iterable of permissions (dicts).

Return type

Iterable[dict[str, Any]]

read(**kwargs: Any) → Dict[str, Any]

Read user propertes.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dictionary of the retrieved user properties.

Raises

CosmosHttpResponseError – If the given user couldn’t be retrieved.

Return type

dict[str, Any]

replace_permission(permission: str, body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Replaces the specified permission if it exists for the user.

If the permission does not already exist, an exception is raised.

Parameters

• permission – The ID (name), dict representing the properties or Permission instance of the permission to be replaced.

• body – A dict-like object representing the permission to replace.

Keyword Arguments

response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the permission after replace went through.

Raises

CosmosHttpResponseError – If the replace failed or the permission with given id does not exist.

Return type

dict[str, Any]

upsert_permission(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission

Insert or update the specified permission.

If the permission already exists in the container, it is replaced. If the permission does not exist, it is inserted.

Parameters

• body – A dict-like object representing the permission to update or insert.

• response_hook (Callable) – A callable invoked with the response metadata.

Returns

A dict representing the upserted permission.

Raises

CosmosHttpResponseError – If the given permission could not be upserted.

Return type

dict[str, Any]