azure.cosmos.aio package¶
-
class
azure.cosmos.aio.
ContainerProxy
(client_connection: azure.cosmos.aio._cosmos_client_connection_async.CosmosClientConnection, database_link: str, id: str, properties: Optional[Dict[str, Any]] = None)[source]¶ An interface to interact with a specific DB Container.
This class should not be instantiated directly. Instead, use the
get_container_client()
method to get an existing container, or thecreate_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
-
async
create_item
(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Create an item in the container.
To update or replace an existing item, use the
ContainerProxy.upsert_item()
method.- Parameters
str] body (dict[str,) – A dict-like object representing the item to create.
- Keyword Arguments
pre_trigger_include (str) – trigger id to be used as pre operation trigger.
post_trigger_include (str) – trigger id to be used as post operation trigger.
indexing_directive (Union[int, IndexingDirective]) – Enumerates the possible values to indicate whether the document should be omitted from indexing. Possible values include: 0 for Default, 1 for Exclude, or 2 for Include.
enable_automatic_id_generation (bool) – Enable automatic id generation if no id present.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – Item with the given ID already exists.
- Returns
A dict representing the new item.
- Return type
Dict[str, Any]
-
async
delete_conflict
(conflict: Union[str, Dict[str, Any]], partition_key: Union[str, int, float, bool], **kwargs: Any) → None[source]¶ Delete a specified conflict from the container.
If the conflict does not already exist in the container, an exception is raised.
- Parameters
- Keyword Arguments
response_hook (Callable[[Dict[str, str], None], None]) – 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
-
async
delete_item
(item: Union[str, Dict[str, Any]], partition_key: Union[str, int, float, bool], **kwargs: Any) → None[source]¶ Delete the specified item from the container.
If the item does not already exist in the container, an exception is raised.
- Parameters
- Keyword Arguments
pre_trigger_include (str) – trigger id to be used as pre operation trigger.
post_trigger_include (str) – trigger id to be used as post operation trigger.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], None], None]) – 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
-
async
get_conflict
(conflict: Union[str, Dict[str, Any]], partition_key: Union[str, int, float, bool], **kwargs: Any) → Dict[str, Any][source]¶ Get the conflict identified by conflict.
-
async
get_throughput
(**kwargs: Any) → azure.cosmos.offer.ThroughputProperties[source]¶ Get the ThroughputProperties object for this container.
If no ThroughputProperties already exists for the container, an exception is raised.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], List[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – No throughput properties exist for the container or the throughput properties could not be retrieved.
- Returns
ThroughputProperties for the container.
- Return type
-
list_conflicts
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all the conflicts in the container.
- Keyword Arguments
- Returns
An AsyncItemPaged of conflicts (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
query_conflicts
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return all conflicts matching a given query.
- Parameters
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
- Keyword Arguments
parameters (List[Dict[str, Any]]) – Optional array of parameters to the query. Ignored if no query is provided.
partition_key (Union[str, int, float, bool]) – Specifies the partition key value for the item. If none is passed in, a cross partition query will be executed.
max_item_count (int) – Max number of items to be returned in the enumeration operation.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of conflicts (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
query_items
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ 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
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
- Keyword Arguments
parameters (List[Dict[str, Any]]) – Optional array of parameters to the query. Each parameter is a dict() with ‘name’ and ‘value’ keys. Ignored if no query is provided.
partition_key (Union[str, int, float, bool]) – Specifies the partition key value for the item. If none is provided, a cross-partition query will be executed.
max_item_count (int) – Max number of items to be returned in the enumeration operation.
enable_scan_in_query (bool) – Allow scan on the queries which couldn’t be served as indexing was opted out on the requested paths.
populate_query_metrics (bool) – Enable returning query metrics in response headers.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
max_integrated_cache_staleness_in_ms (int) – The max cache staleness for the integrated cache in milliseconds. For accounts configured to use the integrated cache, using Session or Eventual consistency, responses are guaranteed to be no staler than this value.
- Returns
An AsyncItemPaged of items (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
Example:
import json async 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))
discontinued_items = container.query_items( query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"', parameters=[dict(name="@model", value="DISCONTINUED")], ) async for item in discontinued_items: print(json.dumps(item, indent=True))
-
query_items_change_feed
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Get a sorted list of items that were changed, in the order in which they were modified.
- Keyword Arguments
is_start_from_beginning (bool) – Get whether change feed should start from beginning (true) or from current (false). By default it’s start from current (false).
partition_key_range_id (str) – ChangeFeed requests can be executed against specific partition key ranges. This is used to process the change feed in parallel across multiple consumers.
continuation (str) – e_tag value to be used as continuation for reading change feed.
max_item_count (int) – Max number of items to be returned in the enumeration operation.
partition_key (Union[str, int, float, bool]) – partition key at which ChangeFeed requests are targeted.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of items (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
async
read
(**kwargs: Any) → Dict[str, Any][source]¶ Read the container properties.
- Keyword Arguments
populate_partition_key_range_statistics (bool) – Enable returning partition key range statistics in response headers.
populate_quota_info (bool) – Enable returning collection storage quota information in response headers.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – 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
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all the items in the container.
- Keyword Arguments
max_item_count (int) – Max number of items to be returned in the enumeration operation.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
max_integrated_cache_staleness_in_ms (int) – The max cache staleness for the integrated cache in milliseconds. For accounts configured to use the integrated cache, using Session or Eventual consistency, responses are guaranteed to be no staler than this value.
- Returns
An AsyncItemPaged of items (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
async
read_item
(item: Union[str, Dict[str, Any]], partition_key: Union[str, int, float, bool], **kwargs: Any) → Dict[str, Any][source]¶ Get the item identified by item.
- Parameters
- Keyword Arguments
post_trigger_include (str) – trigger id to be used as post operation trigger.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
max_integrated_cache_staleness_in_ms (int) – The max cache staleness for the integrated cache in milliseconds. For accounts configured to use the integrated cache, using Session or Eventual consistency, responses are guaranteed to be no staler than this value.
- Raises
CosmosHttpResponseError – The given item couldn’t be retrieved.
- Returns
Dict representing the item to be retrieved.
- Return type
Dict[str, Any]
Example:
item = await container.read_item("item2", partition_key="Widget") item["productModel"] = "DISCONTINUED" updated_item = await container.upsert_item(item)
-
async
replace_item
(item: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ 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
- Keyword Arguments
pre_trigger_include (str) – trigger id to be used as pre operation trigger.
post_trigger_include (str) – trigger id to be used as post operation trigger.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – The replace failed or the item with given id does not exist.
- Returns
A dict representing the item after replace went through.
- Return type
Dict[str, Any]
-
async
replace_throughput
(throughput: Union[int, azure.cosmos.offer.ThroughputProperties], **kwargs: Any) → azure.cosmos.offer.ThroughputProperties[source]¶ Replace the container’s throughput.
If no ThroughputProperties already exist for the container, an exception is raised.
- Parameters
throughput (int) – The throughput to be set (an integer).
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – No throughput properties exist for the container or the throughput properties could not be updated.
- Returns
ThroughputProperties for the container, updated with new throughput.
- Return type
-
async
upsert_item
(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ 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
Any] body (Dict[str,) – A dict-like object representing the item to update or insert.
- Keyword Arguments
pre_trigger_include (str) – trigger id to be used as pre operation trigger.
post_trigger_include (str) – trigger id to be used as post operation trigger.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – The given item could not be upserted.
- Returns
A dict representing the upserted item.
- Return type
Dict[str, Any]
-
property
is_system_key
¶
-
property
scripts
¶
-
class
azure.cosmos.aio.
CosmosClient
(url: str, credential: Union[str, Dict[str, str], azure.core.credentials.TokenCredential], *, consistency_level: Optional[str] = None, **kwargs: Any)[source]¶ 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 (Union[str, Dict[str, str], AsyncTokenCredential]) – Can be the account key, or a dictionary of resource tokens.
- Keyword Arguments
consistency_level (str) – Consistency level to use for the session. Default value is None (account-level). More on consistency levels and possible values: https://aka.ms/cosmos-consistency-levels
Example:
async with CosmosClient(url, key) as client:
Instantiate a new CosmosClient.
-
async
create_database
(id: str, **kwargs: Any) → azure.cosmos.aio._database.DatabaseProxy[source]¶ Create a new database with the given ID (name).
- Parameters
id (str) – ID (name) of the database to create.
- Keyword Arguments
offer_throughput (int or ) – The provisioned throughput for this offer.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosResourceExistsError – Database with the given ID already exists.
- Returns
A DatabaseProxy instance representing the new database.
- Return type
Example:
database_name = "testDatabase" try: database = await client.create_database(id=database_name) except exceptions.CosmosResourceExistsError: database = client.get_database_client(database=database_name)
-
async
create_database_if_not_exists
(id: str, **kwargs: Any) → azure.cosmos.aio._database.DatabaseProxy[source]¶ 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 (str) – ID (name) of the database to read or create.
- Keyword Arguments
offer_throughput (int) – The provisioned throughput for this offer.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – The database read or creation failed.
- Returns
A DatabaseProxy instance representing the database.
- Return type
-
async
delete_database
(database: Union[str, azure.cosmos.aio._database.DatabaseProxy, Dict[str, Any]], **kwargs: Any) → None[source]¶ Delete the database with the given ID (name).
- Parameters
database (Union[str, DatabaseProxy, Dict[str, Any]]) – The ID (name), dict representing the properties, or
DatabaseProxy
instance of the database to delete.- Keyword Arguments
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the database couldn’t be deleted.
- Return type
-
classmethod
from_connection_string
(conn_str: str, *, credential: Optional[Union[str, Dict[str, str]]] = None, consistency_level: Optional[str] = None, **kwargs: Any) → azure.cosmos.aio._cosmos_client.CosmosClient[source]¶ 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.
- Keyword Arguments
credential (Union[str, Dict[str, str]]) – Alternative credentials to use instead of the key provided in the connection string.
consistency_level (str) – Consistency level to use for the session. Default value is None (account-level). More on consistency levels and possible values: https://aka.ms/cosmos-consistency-levels
- Returns
a CosmosClient instance
- Return type
-
get_database_client
(database: Union[str, azure.cosmos.aio._database.DatabaseProxy, Dict[str, Any]]) → azure.cosmos.aio._database.DatabaseProxy[source]¶ Retrieve an existing database with the ID (name) id.
- Parameters
database (Union[str, DatabaseProxy, Dict[str, Any]]) – The ID (name), dict representing the properties, or
DatabaseProxy
instance of the database to get.- Returns
A DatabaseProxy instance representing the retrieved database.
- Return type
-
list_databases
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List the databases in a Cosmos DB SQL database account.
- Keyword Arguments
max_item_count (int) – Max number of items to be returned in the enumeration operation.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of database properties (dicts).
- Return type
-
query_databases
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Query the databases in a Cosmos DB SQL database account.
- Keyword Arguments
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
parameters (List[Dict[str, Any]]) – Optional array of parameters to the query. Each parameter is a dict() with ‘name’ and ‘value’ keys.
max_item_count (int) – Max number of items to be returned in the enumeration operation.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of database properties (dicts).
- Return type
-
class
azure.cosmos.aio.
DatabaseProxy
(client_connection: azure.cosmos.aio._cosmos_client_connection_async.CosmosClientConnection, id: str, properties: Optional[Dict[str, Any]] = None)[source]¶ An interface to interact with a specific database.
This class should not be instantiated directly. Instead use the
get_database_client()
method to get an existing database, or thecreate_database()
method to create a new database.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 (CosmosClientConnection) – Client from which this database was retrieved.
id (str) – ID (name) of the database.
-
async
create_container
(id: str, partition_key: azure.cosmos.partition_key.PartitionKey, **kwargs: Any) → azure.cosmos.aio._container.ContainerProxy[source]¶ Create a new container with the given ID (name).
If a container with the given ID already exists, a CosmosResourceExistsError is raised.
- Parameters
id (str) – ID (name) of container to create.
partition_key (PartitionKey) – The partition key to use for the container.
- Keyword Arguments
str] indexing_policy (dict[str,) – The indexing policy to apply to the container.
default_ttl (int) – Default time to live (TTL) for items in the container. If unspecified, items do not expire.
offer_throughput (int or ) – The provisioned throughput for this offer.
str] unique_key_policy (dict[str,) – The unique key policy to apply to the container.
str] conflict_resolution_policy (dict[str,) – The conflict resolution policy to apply to the container.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
analytical_storage_ttl (int) – Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts.
- Raises
CosmosHttpResponseError – The container creation failed.
- Returns
A ContainerProxy instance representing the new container.
- Return type
Example:
container_name = "products" try: container = await database.create_container( id=container_name, partition_key=PartitionKey(path="/productName") ) except exceptions.CosmosResourceExistsError: container = database.get_container_client(container_name)
customer_container_name = "customers" try: customer_container = await 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)
-
async
create_container_if_not_exists
(id: str, partition_key: azure.cosmos.partition_key.PartitionKey, **kwargs: Any) → azure.cosmos.aio._container.ContainerProxy[source]¶ 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 (str) – ID (name) of container to create.
partition_key (PartitionKey) – The partition key to use for the container.
- Keyword Arguments
str] indexing_policy (dict[str,) – The indexing policy to apply to the container.
default_ttl (int) – Default time to live (TTL) for items in the container. If unspecified, items do not expire.
offer_throughput (int or ) – The provisioned throughput for this offer.
str] unique_key_policy (dict[str,) – The unique key policy to apply to the container.
str] conflict_resolution_policy (dict[str,) – The conflict resolution policy to apply to the container.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
analytical_storage_ttl (int) – Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts.
- Raises
CosmosHttpResponseError – The container creation failed.
- Returns
A ContainerProxy instance representing the new container.
- Return type
-
async
create_user
(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.aio._user.UserProxy[source]¶ Create a new user in the container.
To update or replace an existing user, use the
ContainerProxy.upsert_user()
method.- Parameters
Any] body (Dict[str,) – 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[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the given user couldn’t be created.
- Returns
A UserProxy instance representing the new user.
- Return type
Example:
try: await database.create_user(dict(id="Walter Harp")) print("Created user 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))
-
async
delete_container
(container: Union[str, azure.cosmos.aio._container.ContainerProxy, Dict[str, Any]], **kwargs: Any) → None[source]¶ Delete a container.
- Parameters
container (str or Dict[str, Any] or ContainerProxy) – 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.- Keyword Arguments
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
etag (str) – An ETag value, or the wildcard character (*). Used to check if the resource has changed, and act according to the condition specified by the match_condition parameter.
match_condition (MatchConditions) – The match condition to use upon the etag.
response_hook (Callable[[Dict[str, str], None], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the container couldn’t be deleted.
- Return type
-
async
delete_user
(user: Union[str, azure.cosmos.aio._user.UserProxy, Dict[str, Any]], **kwargs: Any) → None[source]¶ Delete the specified user from the container.
- Parameters
user (Union[str, Dict[str, Any], UserProxy]) – The ID (name), dict representing the properties or
UserProxy
instance of the user to be deleted.- Keyword Arguments
response_hook (Callable[[Dict[str, str], None], None]) – 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
-
get_container_client
(container: Union[str, azure.cosmos.aio._container.ContainerProxy, Dict[str, Any]]) → azure.cosmos.aio._container.ContainerProxy[source]¶ Get a ContainerProxy for a container with specified ID (name).
- Parameters
container (Union[str, Dict[str, Any], ContainerProxy]) – The ID (name), dict representing the properties, or
ContainerProxy
instance of the container to get.- Returns
A ContainerProxy instance representing the container.
- Return type
Example:
database = client.get_database_client(database_name) container = database.get_container_client(container_name)
-
async
get_throughput
(**kwargs: Any) → azure.cosmos.offer.ThroughputProperties[source]¶ Get the ThroughputProperties object for this database.
If no ThroughputProperties already exists for the database, an exception is raised.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], List[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – No throughput properties exist for the database or the throughput properties could not be retrieved.
- Returns
ThroughputProperties for the database.
- Return type
-
get_user_client
(user: Union[str, azure.cosmos.aio._user.UserProxy, Dict[str, Any]]) → azure.cosmos.aio._user.UserProxy[source]¶ Get a UserProxy for a user with specified ID.
-
list_containers
(**kwargs) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List the containers in the database.
- Keyword Arguments
max_item_count (int) – Max number of items to be returned in the enumeration operation.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of container properties (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
Example:
database = client.get_database_client(database_name) async for container in database.list_containers(): print("Container ID: {}".format(container['id']))
-
list_users
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all the users in the container.
- Keyword Arguments
- Returns
An AsyncItemPaged of user properties (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
query_containers
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List the properties for containers in the current database.
- Keyword Arguments
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
parameters (Optional[List[Dict[str, Any]]]) – Optional array of parameters to the query. Each parameter is a dict() with ‘name’ and ‘value’ keys.
max_item_count (int) – Max number of items to be returned in the enumeration operation.
session_token (str) – Token for use with Session consistency.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of container properties (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
query_users
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return all users matching the given query.
- Parameters
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
- Keyword Arguments
parameters (Optional[List[Dict[str, Any]]]) – Optional array of parameters to the query. Each parameter is a dict() with ‘name’ and ‘value’ keys. Ignored if no query is provided.
max_item_count (int) – Max number of users to be returned in the enumeration operation.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of user properties (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
async
read
(**kwargs: Any) → Dict[str, Any][source]¶ Read the database properties.
- Keyword Arguments
- Raises
CosmosHttpResponseError – If the given database couldn’t be retrieved.
- Returns
A dict representing the database properties
- Return type
Dict[str, Any]
-
async
replace_container
(container: Union[str, azure.cosmos.aio._container.ContainerProxy, Dict[str, Any]], partition_key: azure.cosmos.partition_key.PartitionKey, **kwargs: Any) → azure.cosmos.aio._container.ContainerProxy[source]¶ Reset the properties of the container.
Property changes are persisted immediately. Any properties not specified will be reset to their default values.
- Parameters
container (Union[str, Dict[str, Any], ContainerProxy]) – The ID (name), dict representing the properties or
ContainerProxy
instance of the container to be replaced.partition_key (PartitionKey) – The partition key to use for the container.
- Keyword Arguments
str] indexing_policy (dict[str,) – The indexing policy to apply to the container.
default_ttl (int) – Default time to live (TTL) for items in the container. If unspecified, items do not expire.
str] conflict_resolution_policy (dict[str,) – The conflict resolution policy to apply to the container.
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.
str] initial_headers (dict[str,) – Initial headers to be sent as part of the request.
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
analytical_storage_ttl (int) – Analytical store time to live (TTL) for items in the container. A value of None leaves analytical storage off and a value of -1 turns analytical storage on with no TTL. Please note that analytical storage can only be enabled on Synapse Link enabled accounts.
- 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
Example:
# Set the TTL on the container to 3600 seconds (one hour) await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600) # Display the new TTL setting for the container container_props = await database.get_container_client(container_name).read() print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))
-
async
replace_throughput
(throughput: Union[int, azure.cosmos.offer.ThroughputProperties], **kwargs: Any) → azure.cosmos.offer.ThroughputProperties[source]¶ Replace the database-level throughput.
If no ThroughputProperties already exist for the database, an exception is raised.
- Parameters
throughput (int) – The throughput to be set (an integer).
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – No throughput properties exist for the database or the throughput properties could not be updated.
- Returns
ThroughputProperties for the database, updated with new throughput.
- Return type
-
async
replace_user
(user: Union[str, azure.cosmos.aio._user.UserProxy, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → azure.cosmos.aio._user.UserProxy[source]¶ Replaces the specified user if it exists in the container.
- Parameters
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the replace failed or the user with given ID does not exist.
- Returns
A UserProxy instance representing the user after replace went through.
- Return type
-
async
upsert_user
(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.aio._user.UserProxy[source]¶ 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
Any] body (Dict[str,) – A dict-like object representing the user to update or insert.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the given user could not be upserted.
- Returns
A UserProxy instance representing the upserted user.
- Return type
-
class
azure.cosmos.aio.
ScriptsProxy
(container: ContainerProxy, client_connection: azure.cosmos.aio._cosmos_client_connection_async.CosmosClientConnection, container_link: str)[source]¶ An interface to interact with stored procedures.
This class should not be instantiated directly. Instead, use the
ContainerProxy.scripts()
attribute.-
async
create_stored_procedure
(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Create a new stored procedure in the container.
To replace an existing stored procedure, use the
Container.scripts.replace_stored_procedure()
method.- Parameters
Any] body (Dict[str,) – A dict-like object representing the stored procedure to create.
- Raises
CosmosHttpResponseError – If the given stored procedure couldn’t be created.
- Returns
A dict representing the new stored procedure.
- Return type
Dict[str, Any]
-
async
create_trigger
(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Create a trigger in the container.
To replace an existing trigger, use the
ContainerProxy.scripts.replace_trigger()
method.- Parameters
Any] body (Dict[str,) – A dict-like object representing the trigger to create.
- Raises
CosmosHttpResponseError – If the given trigger couldn’t be created.
- Returns
A dict representing the new trigger.
- Return type
Dict[str, Any]
-
async
create_user_defined_function
(body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Create a user-defined function in the container.
To replace an existing user-defined function, use the
ContainerProxy.scripts.replace_user_defined_function()
method.- Parameters
Any] body (Dict[str,) – A dict-like object representing the user-defined function to create.
- Raises
CosmosHttpResponseError – If the user-defined function couldn’t be created.
- Returns
A dict representing the new user-defined function.
- Return type
Dict[str, Any]
-
async
delete_stored_procedure
(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → None[source]¶ 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 (Union[str, Dict[str, Any]]) – The ID (name) or dict representing stored procedure to be deleted.
- Raises
CosmosHttpResponseError – The stored procedure wasn’t deleted successfully.
CosmosResourceNotFoundError – The stored procedure does not exist in the container.
- Return type
-
async
delete_trigger
(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → None[source]¶ Delete a specified trigger from the container.
If the trigger does not already exist in the container, an exception is raised.
- Parameters
trigger (Union[str, Dict[str, Any]]) – 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
-
async
delete_user_defined_function
(udf: Union[str, Dict[str, Any]], **kwargs: Any) → None[source]¶ Delete a specified user-defined function from the container.
If the user-defined function does not already exist in the container, an exception is raised.
- Parameters
udf (Union[str, Dict[str, Any]]) – 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
-
async
execute_stored_procedure
(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any][source]¶ Execute a specified stored procedure.
If the stored procedure does not already exist in the container, an exception is raised.
- Parameters
sproc (Union[str, Dict[str, Any]]) – The ID (name) or dict representing the stored procedure to be executed.
- Keyword Arguments
partition_key (Union[str, int, float, bool]) – Specifies the partition key to indicate which partition the stored procedure should execute on.
parameters (List[Dict[str, Any]]) – 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.
- Raises
CosmosHttpResponseError – If the stored procedure execution failed or if the stored procedure with given id does not exists in the container.
- Returns
Result of the executed stored procedure for the given parameters.
- Return type
Dict[str, Any]
-
async
get_stored_procedure
(sproc: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any][source]¶ Get the stored procedure identified by sproc.
- Parameters
sproc (Union[str, Dict[str, Any]]) – The ID (name) or dict representing the stored procedure to retrieve.
- Raises
CosmosHttpResponseError – If the given stored procedure couldn’t be retrieved.
- Returns
A dict representing the retrieved stored procedure.
- Return type
Dict[str, Any]
-
async
get_trigger
(trigger: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any][source]¶ Get a trigger identified by id.
- Parameters
trigger (Union[str, Dict[str, Any]]) – The ID (name) or dict representing trigger to retrieve.
- Raises
CosmosHttpResponseError – If the given trigger couldn’t be retrieved.
- Returns
A dict representing the retrieved trigger.
- Return type
Dict[str, Any]
-
async
get_user_defined_function
(udf: Union[str, Dict[str, Any]], **kwargs: Any) → Dict[str, Any][source]¶ Get a user-defined function identified by id.
- Parameters
udf (Union[str, Dict[str, Any]]) – The ID (name) or dict representing udf to retrieve.
- Raises
CosmosHttpResponseError – If the user-defined function couldn’t be retrieved.
- Returns
A dict representing the retrieved user-defined function.
- Return type
Dict[str, Any]
-
list_stored_procedures
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all stored procedures in the container.
-
list_triggers
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all triggers in the container.
-
list_user_defined_functions
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all the user-defined functions in the container.
-
query_stored_procedures
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return all stored procedures matching the given query.
-
query_triggers
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return all triggers matching the given query.
-
query_user_defined_functions
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return user-defined functions matching a given query.
-
async
replace_stored_procedure
(sproc: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Replace a specified stored procedure in the container.
If the stored procedure does not already exist in the container, an exception is raised.
- Parameters
- Raises
CosmosHttpResponseError – If the replace failed or the stored procedure with given id does not exist.
- Returns
A dict representing the stored procedure after replace went through.
- Return type
Dict[str, Any]
-
async
replace_trigger
(trigger: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Replace a specified trigger in the container.
If the trigger does not already exist in the container, an exception is raised.
- Parameters
- Raises
CosmosHttpResponseError – If the replace failed or the trigger with given id does not exist.
- Returns
A dict representing the trigger after replace went through.
- Return type
Dict[str, Any]
-
async
replace_user_defined_function
(udf: Union[str, Dict[str, Any]], body: Dict[str, Any], **kwargs: Any) → Dict[str, Any][source]¶ Replace a specified user-defined function in the container.
If the user-defined function does not already exist in the container, an exception is raised.
- Parameters
- Raises
CosmosHttpResponseError – If the replace failed or the user-defined function with the given id does not exist.
- Returns
A dict representing the user-defined function after replace went through.
- Return type
Dict[str, Any]
-
async
-
class
azure.cosmos.aio.
UserProxy
(client_connection: azure.cosmos.aio._cosmos_client_connection_async.CosmosClientConnection, id: str, database_link: str, properties: Optional[Dict[str, Any]] = None)[source]¶ An interface to interact with a specific user.
This class should not be instantiated directly. Instead, use the
DatabaseProxy.get_user_client()
method.-
async
create_permission
(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission[source]¶ Create a permission for the user.
To update or replace an existing permission, use the
UserProxy.upsert_permission()
method.- Parameters
body (Dict[str, Any]) – A dict-like object representing the permission to create.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the given permission couldn’t be created.
- Returns
A permission object representing the new permission.
- Return type
-
async
delete_permission
(permission: Union[str, Dict[str, Any], azure.cosmos.permission.Permission], **kwargs: Any) → None[source]¶ Delete the specified permission from the user.
If the permission does not already exist, an exception is raised.
- Parameters
permission (Union[str, Dict[str, Any], Permission]) – The ID (name), dict representing the properties or
Permission
instance of the permission to be deleted.- Keyword Arguments
response_hook (Callable[[Dict[str, str], None], None]) – 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
-
async
get_permission
(permission: Union[str, Dict[str, Any], azure.cosmos.permission.Permission], **kwargs: Any) → azure.cosmos.permission.Permission[source]¶ Get the permission identified by id.
- Parameters
permission (Union[str, Dict[str, Any], Permission]) – The ID (name), dict representing the properties or
Permission
instance of the permission to be retrieved.- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the given permission couldn’t be retrieved.
- Returns
The retrieved permission object.
- Return type
-
list_permissions
(**kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ List all permission for the user.
- Keyword Arguments
- Returns
An AsyncItemPaged of permissions (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
query_permissions
(query: Union[str, Dict[str, Any]], **kwargs: Any) → azure.core.async_paging.AsyncItemPaged[Dict[str, Any]][source]¶ Return all permissions matching the given query.
- Parameters
Dict[str, Any]] query (Union[str,) – The Azure Cosmos DB SQL query to execute.
- Keyword Arguments
parameters (Optional[List[Dict[str, Any]]]) – Optional array of parameters to the query. Ignored if no query is provided.
max_item_count (int) – Max number of permissions to be returned in the enumeration operation.
response_hook (Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None]) – A callable invoked with the response metadata.
- Returns
An AsyncItemPaged of permissions (dicts).
- Return type
AsyncItemPaged[Dict[str, Any]]
-
async
replace_permission
(permission: Union[str, Dict[str, Any], azure.cosmos.permission.Permission], body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission[source]¶ Replaces the specified permission if it exists for the user.
If the permission does not already exist, an exception is raised.
- Parameters
permission (Union[str, Dict[str, Any], Permission]) – The ID (name), dict representing the properties or
Permission
instance of the permission to be replaced.body (Dict[str, Any]) – A dict-like object representing the permission to replace.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the replace failed or the permission with given id does not exist.
- Returns
A permission object representing the permission after the replace went through.
- Return type
-
async
upsert_permission
(body: Dict[str, Any], **kwargs: Any) → azure.cosmos.permission.Permission[source]¶ 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 (Dict[str, Any]) – A dict-like object representing the permission to update or insert.
- Keyword Arguments
response_hook (Callable[[Dict[str, str], Dict[str, Any]], None]) – A callable invoked with the response metadata.
- Raises
CosmosHttpResponseError – If the given permission could not be upserted.
- Returns
A dict representing the upserted permission.
- Return type
-
async