DatabaseProxy Class

Reference

An interface to interact with a specific database.

This class should not be instantiated directly. Instead use the <xref: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.

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.

Inheritance: builtins.object

DatabaseProxy

Constructor

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] | None = None)

Parameters

Name	Description
client_connection Required	<xref:ClientSession> Client from which this database was retrieved.
id Required	str ID (name) of the database.
properties	Default value: None

Variables

Name	Description
id	The ID (name) of the database.

Methods

create_container	Create a new container with the given ID (name). If a container with the given ID already exists, a CosmosResourceExistsError is raised.
create_container_if_not_exists	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.
create_user	Create a new user in the container. To update or replace an existing user, use the <xref:ContainerProxy.upsert_user> method.
delete_container	Delete a container.
delete_user	Delete the specified user from the container.
get_container_client	Get a ContainerProxy for a container with specified ID (name).
get_throughput	Get the ThroughputProperties object for this database. If no ThroughputProperties already exist for the database, an exception is raised.
get_user_client	Get a UserProxy for a user with specified ID.
list_containers	List the containers in the database.
list_users	List all the users in the container.
query_containers	List the properties for containers in the current database.
query_users	Return all users matching the given query.
read	Read the database properties.
read_offer	Get the ThroughputProperties object for this database. If no ThroughputProperties already exist for the database, an exception is raised.
replace_container	Reset the properties of the container. Property changes are persisted immediately. Any properties not specified will be reset to their default values.
replace_throughput	Replace the database-level throughput.
replace_user	Replaces the specified user if it exists in the container.
upsert_user	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.

create_container

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

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

create_container(id: str, partition_key: PartitionKey, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, analytical_storage_ttl: int | None = None, vector_embedding_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parameters

Name	Description
id Required	str ID (name) of container to create.
partition_key Required	PartitionKey The partition key to use for the container.
indexing_policy Required	Dict[str, Any] The indexing policy to apply to the container.
default_ttl Required	int Default time to live (TTL) for items in the container. If unused, items do not expire.
offer_throughput Required	Union[int, ThroughputProperties] The provisioned throughput for this offer.
unique_key_policy Required	Dict[str, Any] The unique key policy to apply to the container.
conflict_resolution_policy Required	Dict[str, Any] The conflict resolution policy to apply to the container.

Keyword-Only Parameters

Name	Description
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.
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.
computed_properties	List[Dict[str, str]] provisional Sets The computed properties for this container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet
vector_embedding_policy	Dict[str, Any] provisional The vector embedding policy for the container. Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and is generated for a particular distance function.

Returns

Type	Description
ContainerProxy	A ContainerProxy instance representing the new container.

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

Examples

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

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.

create_container_if_not_exists(id: str, partition_key: PartitionKey, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, analytical_storage_ttl: int | None = None, vector_embedding_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parameters

Name	Description
id Required	str ID (name) of container to create.
partition_key Required	PartitionKey The partition key to use for the container.
indexing_policy Required	Dict[str, Any] The indexing policy to apply to the container.
default_ttl Required	int Default time to live (TTL) for items in the container. If unused, items do not expire.
offer_throughput Required	Union[int, ThroughputProperties] The provisioned throughput for this offer.
unique_key_policy Required	Dict[str, Any] The unique key policy to apply to the container.
conflict_resolution_policy Required	Dict[str, Any] The conflict resolution policy to apply to the container.

Keyword-Only Parameters

Name	Description
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.
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.
computed_properties	List[Dict[str, str]] provisional Sets The computed properties for this container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet
vector_embedding_policy	Dict[str, Any] The vector embedding policy for the container. Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and is generated for a particular distance function.

Returns

Type	Description
ContainerProxy	A ContainerProxy instance representing the container.

Exceptions

Type	Description
CosmosHttpResponseError	The container read or creation failed.

create_user

Create a new user in the container.

To update or replace an existing user, use the <xref:ContainerProxy.upsert_user> method.

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameters

Name	Description
body Required	Dict[str, Any] 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-Only Parameters

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

Returns

Type	Description
UserProxy	A UserProxy instance representing the new user.

Exceptions

Type	Description
CosmosHttpResponseError	If the given user couldn't be created.

Examples

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

Delete a container.

delete_container(container: str | ContainerProxy | Mapping[str, Any], populate_query_metrics: bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> None

Parameters

Name	Description
container Required	Union[str, ContainerProxy, Dict[str, Any]] 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-Only Parameters

Name	Description
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

Type	Description
None

Exceptions

Type	Description
CosmosHttpResponseError	If the container couldn't be deleted.

delete_user

Delete the specified user from the container.

delete_user(user: str | UserProxy | Mapping[str, Any], **kwargs: Any) -> None

Parameters

Name	Description
user Required	Union[str, UserProxy, Dict[str, Any]] The ID (name), dict representing the properties or UserProxy instance of the user to be deleted.

Keyword-Only Parameters

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

Returns

Type	Description
None

Exceptions

Type	Description
CosmosHttpResponseError	The user wasn't deleted successfully.
CosmosResourceNotFoundError	The user does not exist in the container.

get_container_client

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

get_container_client(container: str | ContainerProxy | Mapping[str, Any]) -> ContainerProxy

Parameters

Name	Description
container Required	Union[str, ContainerProxy, Dict[str, Any]] The ID (name) of the container, a ContainerProxy instance, or a dict representing the properties of the container to be retrieved.

Keyword-Only Parameters

Name	Description
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.
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.
computed_properties	List[Dict[str, str]] provisional Sets The computed properties for this container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet
vector_embedding_policy	Dict[str, Any] provisional The vector embedding policy for the container. Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and is generated for a particular distance function.

Returns

Type	Description
ContainerProxy	A ContainerProxy instance representing the retrieved database.

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

Examples

Get an existing container, handling a failure if encountered:


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

get_throughput

Get the ThroughputProperties object for this database.

If no ThroughputProperties already exist for the database, an exception is raised.

get_throughput(**kwargs: Any) -> ThroughputProperties

Keyword-Only Parameters

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

Returns

Type	Description
ThroughputProperties	ThroughputProperties for the database.

Exceptions

Type	Description
CosmosHttpResponseError	No throughput properties exists for the container or the throughput properties could not be retrieved.

get_user_client

Get a UserProxy for a user with specified ID.

get_user_client(user: str | UserProxy | Mapping[str, Any]) -> UserProxy

Parameters

Name	Description
user Required	Union[str, UserProxy, Dict[str, Any]] The ID (name), dict representing the properties or UserProxy instance of the user to be retrieved.

Keyword-Only Parameters

Name	Description
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.
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.
computed_properties	List[Dict[str, str]] provisional Sets The computed properties for this container in the Azure Cosmos DB Service. For more Information on how to use computed properties visit here: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/query/computed-properties?tabs=dotnet
vector_embedding_policy	Dict[str, Any] provisional The vector embedding policy for the container. Each vector embedding possesses a predetermined number of dimensions, is associated with an underlying data type, and is generated for a particular distance function.

Returns

Type	Description
UserProxy	A UserProxy instance representing the retrieved user.

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

list_containers

List the containers in the database.

list_containers(max_item_count: int | None = None, populate_query_metrics: bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
max_item_count Required	int Max number of items to be returned in the enumeration operation.

Keyword-Only Parameters

Name	Description
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

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

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

Examples

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

List all the users in the container.

list_users(max_item_count: int | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
max_item_count Required	int Max number of users to be returned in the enumeration operation.

Keyword-Only Parameters

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

Returns

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

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

query_containers

List the properties for containers in the current database.

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

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.
parameters Required	List[Dict[str, Any]] Optional array of parameters to the query. Ignored if no query is provided.
max_item_count Required	int Max number of items to be returned in the enumeration operation.

Keyword-Only Parameters

Name	Description
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

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

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

query_users

Return all users matching the given query.

query_users(query: str, parameters: List[Dict[str, Any]] | None = None, max_item_count: int | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.
parameters Required	List[Dict[str, Any]] Optional array of parameters to the query. Ignored if no query is provided.
max_item_count Required	int Max number of users to be returned in the enumeration operation.

Keyword-Only Parameters

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

Returns

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

Exceptions

Type	Description
CosmosHttpResponseError	The container creation failed.

read

Read the database properties.

read(populate_query_metrics: bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]

Keyword-Only Parameters

Name	Description
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

Type	Description
Dict[<xref:Str>, Any]	A dict representing the database properties.

Exceptions

Type	Description
CosmosHttpResponseError	If the given database couldn't be retrieved.

read_offer

Get the ThroughputProperties object for this database.

If no ThroughputProperties already exist for the database, an exception is raised.

read_offer(**kwargs: Any) -> ThroughputProperties

Keyword-Only Parameters

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

Returns

Type	Description
ThroughputProperties	ThroughputProperties for the database.

Exceptions

Type	Description
CosmosHttpResponseError	No throughput properties exists for the container or the throughput properties could not be retrieved.

replace_container

Reset the properties of the container.

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

replace_container(container: str | ContainerProxy | Mapping[str, Any], partition_key: PartitionKey, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, *, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, analytical_storage_ttl: int | None = None, **kwargs: Any) -> ContainerProxy

Parameters

Name	Description
container Required	Union[str, ContainerProxy, Dict[str, Any]] The ID (name), dict representing the properties or ContainerProxy instance of the container to be replaced.
partition_key Required	PartitionKey The partition key to use for the container.
indexing_policy Required	Dict[str, Any] The indexing policy to apply to the container.
default_ttl Required	int Default time to live (TTL) for items in the container. If unspecified, items do not expire.
conflict_resolution_policy Required	Dict[str, Any] The conflict resolution policy to apply to the container.

Keyword-Only Parameters

Name	Description
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.
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.
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
ContainerProxy	A ContainerProxy instance representing the container after replace completed.

Exceptions

Type	Description
CosmosHttpResponseError	Raised if the container couldn't be replaced. This includes if the container with given id does not exist.

Examples

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

Replace the database-level throughput.

replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputProperties

Parameters

Name	Description
throughput Required	Union[int, ThroughputProperties] The throughput to be set (an integer).

Keyword-Only Parameters

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

Returns

Type	Description
ThroughputProperties	ThroughputProperties for the database, updated with new throughput.

Exceptions

Type	Description
CosmosHttpResponseError	If no throughput properties exists for the database or if the throughput properties could not be updated.

replace_user

Replaces the specified user if it exists in the container.

replace_user(user: str | UserProxy | Mapping[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameters

Name	Description
user Required	Union[str, UserProxy, Dict[str, Any]] The ID (name), dict representing the properties or UserProxy instance of the user to be replaced.
body Required	Dict[str, Any] A dict-like object representing the user to replace.

Keyword-Only Parameters

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

Returns

Type	Description
UserProxy	A UserProxy instance representing the user after replace went through.

Exceptions

Type	Description
CosmosHttpResponseError	If the replace operation failed or the user with given ID does not exist.

upsert_user

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.

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parameters

Name	Description
body Required	Dict[str, Any] A dict-like object representing the user to update or insert.

Keyword-Only Parameters

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

Returns

Type	Description
UserProxy	A UserProxy instance representing the upserted user.

Exceptions

Type	Description
CosmosHttpResponseError	If the given user could not be upserted.

Share via

DatabaseProxy Class

Constructor

Parameters

Variables

Methods

create_container

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

create_container_if_not_exists

Parameters

Keyword-Only Parameters

Returns

Exceptions

create_user

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

delete_container

Parameters

Keyword-Only Parameters

Returns

Exceptions

delete_user

Parameters

Keyword-Only Parameters

Returns

Exceptions

get_container_client

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

get_throughput

Keyword-Only Parameters

Returns

Exceptions

get_user_client

Parameters

Keyword-Only Parameters

Returns

Exceptions

list_containers

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

list_users

Parameters

Keyword-Only Parameters

Returns

Exceptions

query_containers

Parameters

Keyword-Only Parameters

Returns

Exceptions

query_users

Parameters

Keyword-Only Parameters

Returns

Exceptions

read

Keyword-Only Parameters

Returns

Exceptions

read_offer

Keyword-Only Parameters

Returns

Exceptions

replace_container

Parameters

Keyword-Only Parameters