DatabaseProxy Class
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 the create_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.
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.objectDatabaseProxy
Constructor
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] | None = None)
Parameters
Name | Description |
---|---|
client_connection
Required
|
<xref:azure.cosmos.aio.CosmosClientConnection>
Client from which this database was retrieved. |
id
Required
|
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 exists 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. |
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. If no ThroughputProperties already exist for the database, an exception is raised. |
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.
async create_container(id: str, partition_key: PartitionKey, *, indexing_policy: Dict[str, str] | None = None, default_ttl: int | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, str] | None = None, conflict_resolution_policy: Dict[str, str] | 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
|
ID (name) of container to create. |
partition_key
Required
|
The partition key to use for the container. |
Keyword-Only Parameters
Name | Description |
---|---|
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. |
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. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
etag
|
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
|
The match condition to use upon the etag. |
computed_properties
|
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 |
response_hook
|
A callable invoked with the response metadata. |
analytical_storage_ttl
|
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. |
vector_embedding_policy
|
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 |
---|---|
A ContainerProxy instance representing the new container. |
Exceptions
Type | Description |
---|---|
The container creation failed. |
Examples
Create a container with default settings:
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)
Create a container with specific settings; in this case, a custom partition key:
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)
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.
async create_container_if_not_exists(id: str, partition_key: PartitionKey, *, indexing_policy: Dict[str, str] | None = None, default_ttl: int | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, str] | None = None, conflict_resolution_policy: Dict[str, str] | 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
|
ID (name) of container to create. |
partition_key
Required
|
The partition key to use for the container. |
Keyword-Only Parameters
Name | Description |
---|---|
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. |
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. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
etag
|
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
|
The match condition to use upon the etag. |
computed_properties
|
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 |
response_hook
|
A callable invoked with the response metadata. |
analytical_storage_ttl
|
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. |
vector_embedding_policy
|
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 |
---|---|
A ContainerProxy instance representing the new container. |
Exceptions
Type | Description |
---|---|
The container 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.
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy
Parameters
Name | Description |
---|---|
body
Required
|
A dict 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
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
A UserProxy instance representing the new user. |
Exceptions
Type | Description |
---|---|
If the given user couldn't be created. |
Examples
Create a database user:
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))
delete_container
Delete a container.
async delete_container(container: str | ContainerProxy | Mapping[str, Any], *, 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
|
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
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
etag
|
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
|
The match condition to use upon the etag. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
Exceptions
Type | Description |
---|---|
If the container couldn't be deleted. |
delete_user
Delete the specified user from the container.
async delete_user(user: str | UserProxy | Mapping[str, Any], **kwargs: Any) -> None
Parameters
Name | Description |
---|---|
user
Required
|
The ID (name), dict representing the properties or UserProxy instance of the user to be deleted. |
Keyword-Only Parameters
Name | Description |
---|---|
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
Exceptions
Type | Description |
---|---|
The user wasn't deleted successfully. |
|
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 | Dict[str, Any]) -> ContainerProxy
Parameters
Name | Description |
---|---|
container
Required
|
The ID (name), dict representing the properties, or ContainerProxy instance of the container to get. |
Keyword-Only Parameters
Name | Description |
---|---|
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. |
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. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
etag
|
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
|
The match condition to use upon the etag. |
computed_properties
|
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 |
response_hook
|
A callable invoked with the response metadata. |
analytical_storage_ttl
|
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. |
vector_embedding_policy
|
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 |
---|---|
A ContainerProxy instance representing the container. |
Exceptions
Type | Description |
---|---|
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 exists for the database, an exception is raised.
async get_throughput(**kwargs: Any) -> ThroughputProperties
Keyword-Only Parameters
Name | Description |
---|---|
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
ThroughputProperties for the database. |
Exceptions
Type | Description |
---|---|
No throughput properties exist for the database 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
|
The ID (name), dict representing the properties, or UserProxy instance of the user to get. |
Keyword-Only Parameters
Name | Description |
---|---|
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. |
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. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
etag
|
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
|
The match condition to use upon the etag. |
computed_properties
|
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 |
response_hook
|
A callable invoked with the response metadata. |
analytical_storage_ttl
|
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. |
vector_embedding_policy
|
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 |
---|---|
A UserProxy instance representing the retrieved user. |
Exceptions
Type | Description |
---|---|
The container creation failed. |
list_containers
List the containers in the database.
list_containers(*, session_token: str | None = None, max_item_count: int | None = None, initial_headers: Dict[str, str] | None = None, **kwargs) -> AsyncItemPaged[Dict[str, Any]]
Keyword-Only Parameters
Name | Description |
---|---|
max_item_count
|
Max number of items to be returned in the enumeration operation. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
An AsyncItemPaged of container properties (dicts). |
Exceptions
Type | Description |
---|---|
The container creation failed. |
Examples
List all containers in the database:
database = client.get_database_client(database_name)
async 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) -> AsyncItemPaged[Dict[str, Any]]
Keyword-Only Parameters
Name | Description |
---|---|
max_item_count
|
Max number of users to be returned in the enumeration operation. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
An AsyncItemPaged of user properties (dicts). |
Exceptions
Type | Description |
---|---|
The container creation failed. |
query_containers
List the properties for containers in the current database.
query_containers(query: str, *, parameters: List[Dict[str, Any]] | None = None, session_token: str | None = None, max_item_count: int | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]
Parameters
Name | Description |
---|---|
query
Required
|
The Azure Cosmos DB SQL query to execute. |
Keyword-Only Parameters
Name | Description |
---|---|
parameters
|
Optional array of parameters to the query. Each parameter is a dict() with 'name' and 'value' keys. |
max_item_count
|
Max number of items to be returned in the enumeration operation. |
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
An AsyncItemPaged of container properties (dicts). |
Exceptions
Type | Description |
---|---|
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) -> AsyncItemPaged[Dict[str, Any]]
Parameters
Name | Description |
---|---|
query
Required
|
The Azure Cosmos DB SQL query to execute. |
Keyword-Only Parameters
Name | Description |
---|---|
parameters
|
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
|
Max number of users to be returned in the enumeration operation. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
An AsyncItemPaged of user properties (dicts). |
Exceptions
Type | Description |
---|---|
The container creation failed. |
read
Read the database properties.
async read(*, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]
Keyword-Only Parameters
Name | Description |
---|---|
session_token
|
Token for use with Session consistency. |
initial_headers
|
Initial headers to be sent as part of the request. |
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
A dict representing the database properties |
Exceptions
Type | Description |
---|---|
If the given database couldn't 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.
async replace_container(container: str | ContainerProxy | Mapping[str, Any], partition_key: PartitionKey, *, indexing_policy: Dict[str, str] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, str] | 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
|
The ID (name), dict representing the properties or ContainerProxy instance of the container to be replaced. |
partition_key
Required
|
The partition key to use for the container. |
Keyword-Only Parameters
Name | Description |
---|---|
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. |
session_token
|
Token for use with Session consistency. |
etag
|
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
|
The match condition to use upon the etag. |
initial_headers
|
Initial headers to be sent as part of the request. |
analytical_storage_ttl
|
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
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
A ContainerProxy instance representing the container after replace completed. |
Exceptions
Type | Description |
---|---|
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)
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'])))
replace_throughput
Replace the database-level throughput.
If no ThroughputProperties already exist for the database, an exception is raised.
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputProperties
Parameters
Name | Description |
---|---|
throughput
Required
|
The throughput to be set. |
Keyword-Only Parameters
Name | Description |
---|---|
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
ThroughputProperties for the database, updated with new throughput. |
Exceptions
Type | Description |
---|---|
No throughput properties exist for the database or the throughput properties could not be updated. |
replace_user
Replaces the specified user if it exists in the container.
async replace_user(user: str | UserProxy | Mapping[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy
Parameters
Name | Description |
---|---|
user
Required
|
The ID (name), dict representing the properties or UserProxy instance of the user to be replaced. |
body
Required
|
A dict object representing the user to replace. |
Keyword-Only Parameters
Name | Description |
---|---|
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
A UserProxy instance representing the user after replace went through. |
Exceptions
Type | Description |
---|---|
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.
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy
Parameters
Name | Description |
---|---|
body
Required
|
A dict-like object representing the user to update or insert. |
Keyword-Only Parameters
Name | Description |
---|---|
response_hook
|
A callable invoked with the response metadata. |
Returns
Type | Description |
---|---|
A UserProxy instance representing the upserted user. |
Exceptions
Type | Description |
---|---|
If the given user could not be upserted. |
Azure SDK for Python