ContainerProxy Class

Reference

An interface to interact with a specific DB Container.

This class should not be instantiated directly. Instead, use the <xref:azure.cosmos.aio.database.DatabaseProxy.get_container_client> method to get an existing container, or the <xref:azure.cosmos.aio.database.DatabaseProxy.create_container> method to create a new container.

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

Inheritance: builtins.object

ContainerProxy

Constructor

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

Parameters

Name	Description
client_connection Required
database_link Required
id Required
properties	Default value: None

Variables

Name	Description
id	str ID (name) of the container
session_token	str The session token for the container.

Methods

create_item	Create an item in the container. To update or replace an existing item, use the upsert_item method.
delete_all_items_by_partition_key	The delete by partition key feature is an asynchronous, background operation that allows you to delete all documents with the same logical partition key value, using the Cosmos SDK. The delete by partition key operation is constrained to consume at most 10% of the total available RU/s on the container each second. This helps in limiting the resources used by this background task.
delete_conflict	Delete a specified conflict from the container. If the conflict does not already exist in the container, an exception is raised.
delete_item	Delete the specified item from the container. If the item does not already exist in the container, an exception is raised.
execute_item_batch	Executes the transactional batch for the specified partition key.
feed_range_from_partition_key	Gets the feed range for a given partition key. :param partition_key: partition key to get feed range. :type partition_key: PartitionKeyType :returns: a feed range :rtype: Dict[str, Any] Warning The structure of the dict representation of a feed range may vary, including which keys are present. It therefore should only be treated as an opaque value.
get_conflict	Get the conflict identified by conflict.
get_latest_session_token	provisional This method is still in preview and may be subject to breaking changes. Gets the the most up to date session token from the list of session token and feed range tuples for a specific target feed range. The feed range can be obtained from a partition key or by reading the container feed ranges. This should only be used if maintaining own session token or else the CosmosClient instance will keep track of session token. Session tokens and feed ranges are scoped to a container. Only input session tokens and feed ranges obtained from the same container. :param feed_ranges_to_session_tokens: List of feed range and session token tuples. :type feed_ranges_to_session_tokens: List[Tuple[Dict[str, Any], str]] :param target_feed_range: feed range to get most up to date session token. :type target_feed_range: Dict[str, Any] :returns: a session token :rtype: str
get_throughput	Get the ThroughputProperties object for this container. If no ThroughputProperties already exists for the container, an exception is raised.
is_feed_range_subset	Checks if child feed range is a subset of parent feed range. :param parent_feed_range: left feed range :type parent_feed_range: Dict[str, Any] :param child_feed_range: right feed range :type child_feed_range: Dict[str, Any] :returns: a boolean indicating if child feed range is a subset of parent feed range :rtype: bool Warning The structure of the dict representation of a feed range may vary, including which keys are present. It therefore should only be treated as an opaque value.
list_conflicts	List all the conflicts in the container.
patch_item	Patches the specified item with the provided operations if it exists in the container. If the item does not already exist in the container, an exception is raised.
query_conflicts	Return all conflicts matching a given query.
query_items	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.
query_items_change_feed	Get a sorted list of items that were changed, in the order in which they were modified.
read	Read the container properties.
read_all_items	List all the items in the container.
read_feed_ranges	Obtains a list of feed ranges that can be used to parallelize feed operations. Warning The structure of the dict representation of a feed range may vary, including which keys are present. It therefore should only be treated as an opaque value.
read_item	Get the item identified by item.
replace_item	Replaces the specified item if it exists in the container. If the item does not already exist in the container, an exception is raised.
replace_throughput	Replace the container's throughput. If no ThroughputProperties already exist for the container, an exception is raised.
upsert_item	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.

create_item

Create an item in the container.

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

async create_item(body: Dict[str, Any], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, indexing_directive: int | None = None, enable_automatic_id_generation: bool = False, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, no_response: bool | None = None, **kwargs: Any) -> CosmosDict

Parameters

Name	Description
body Required	dict[str, str] A dict-like object representing the item to create.

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Returns

Type	Description
CosmosDict[str, Any]	A CosmosDict representing the new item. The dict will be empty if no_response is specified.

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

delete_all_items_by_partition_key

The delete by partition key feature is an asynchronous, background operation that allows you to delete all documents with the same logical partition key value, using the Cosmos SDK. The delete by partition key operation is constrained to consume at most 10% of the total available RU/s on the container each second. This helps in limiting the resources used by this background task.

async delete_all_items_by_partition_key(partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> None

Parameters

Name	Description
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] Partition key for the items to be deleted.

Keyword-Only Parameters

Name	Description
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.
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	Item with the given ID already exists.

delete_conflict

Delete a specified conflict from the container.

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

async delete_conflict(conflict: str | Mapping[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], **kwargs: Any) -> None

Parameters

Name	Description
conflict Required	Union[str, Dict[str, Any]] The ID (name) or dict representing the conflict to retrieve.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] Partition key for the conflict to retrieve.

Keyword-Only Parameters

Name	Description
response_hook	Callable[[Dict[str, str], None], None] A callable invoked with the response metadata.

Returns

Type	Description
None

Exceptions

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

delete_item

Delete the specified item from the container.

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

async delete_item(item: str | Mapping[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> None

Parameters

Name	Description
item Required	Union[str, Dict[str, Any]] The ID (name) or dict representing item to be deleted.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] Specifies the partition key value for the item.

Keyword-Only Parameters

Name	Description
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.
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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
response_hook	Callable[[Dict[str, str], None], None] A callable invoked with the response metadata.

Returns

Type	Description
None

Exceptions

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

execute_item_batch

Executes the transactional batch for the specified partition key.

async execute_item_batch(batch_operations: Sequence[Tuple[str, Tuple[Any, ...]] | Tuple[str, Tuple[Any, ...], Dict[str, Any]]], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> CosmosList

Parameters

Name	Description
batch_operations Required	List[Tuple[Any]] The batch of operations to be executed.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] The partition key value of the batch operations.

Keyword-Only Parameters

Name	Description
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.
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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
CosmosList[Dict[str, Any]]	A CosmosList representing the items after the batch operations went through.

Exceptions

Type	Description
CosmosHttpResponseError	The batch failed to execute.
CosmosBatchOperationError	A transactional batch operation failed in the batch.

feed_range_from_partition_key

Gets the feed range for a given partition key. :param partition_key: partition key to get feed range. :type partition_key: PartitionKeyType :returns: a feed range :rtype: Dict[str, Any]

Warning

The structure of the dict representation of a feed range may vary, including which keys

are present. It therefore should only be treated as an opaque value.

async feed_range_from_partition_key(partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue]) -> Dict[str, Any]

Parameters

Name	Description
partition_key Required

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

get_conflict

Get the conflict identified by conflict.

async get_conflict(conflict: str | Mapping[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], **kwargs: Any) -> Dict[str, Any]

Parameters

Name	Description
conflict Required	Union[str, Dict[str, Any]] The ID (name) or dict representing the conflict to retrieve.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] Partition key for the conflict to retrieve.

Keyword-Only Parameters

Name	Description
response_hook	Callable[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.

Returns

Type	Description
Dict[str, Any]	A dict representing the retrieved conflict.

Exceptions

Type	Description
CosmosHttpResponseError	The given conflict couldn't be retrieved.

get_latest_session_token

provisional This method is still in preview and may be subject to breaking changes.

Gets the the most up to date session token from the list of session token and feed range tuples for a specific target feed range. The feed range can be obtained from a partition key or by reading the container feed ranges. This should only be used if maintaining own session token or else the CosmosClient instance will keep track of session token. Session tokens and feed ranges are scoped to a container. Only input session tokens and feed ranges obtained from the same container. :param feed_ranges_to_session_tokens: List of feed range and session token tuples. :type feed_ranges_to_session_tokens: List[Tuple[Dict[str, Any], str]] :param target_feed_range: feed range to get most up to date session token. :type target_feed_range: Dict[str, Any] :returns: a session token :rtype: str

async get_latest_session_token(feed_ranges_to_session_tokens: List[Tuple[Dict[str, Any], str]], target_feed_range: Dict[str, Any]) -> str

Parameters

Name	Description
feed_ranges_to_session_tokens Required
target_feed_range Required

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

get_throughput

Get the ThroughputProperties object for this container.

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

async get_throughput(**kwargs: Any) -> ThroughputProperties

Keyword-Only Parameters

Name	Description
response_hook	Callable[[Dict[str, str], List[Dict[str, Any]]], None] A callable invoked with the response metadata.

Returns

Type	Description
ThroughputProperties	ThroughputProperties for the container.

Exceptions

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

is_feed_range_subset

Checks if child feed range is a subset of parent feed range. :param parent_feed_range: left feed range :type parent_feed_range: Dict[str, Any] :param child_feed_range: right feed range :type child_feed_range: Dict[str, Any] :returns: a boolean indicating if child feed range is a subset of parent feed range :rtype: bool

Warning

The structure of the dict representation of a feed range may vary, including which keys

are present. It therefore should only be treated as an opaque value.

async is_feed_range_subset(parent_feed_range: Dict[str, Any], child_feed_range: Dict[str, Any]) -> bool

Parameters

Name	Description
parent_feed_range Required
child_feed_range Required

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

list_conflicts

List all the conflicts in the container.

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

Keyword-Only Parameters

Name	Description
max_item_count	int Max number of items to be returned in the enumeration operation.
response_hook	Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None] A callable invoked with the response metadata.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, Any]]	An AsyncItemPaged of conflicts (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

patch_item

Patches the specified item with the provided operations if it exists in the container.

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

async patch_item(item: str | Dict[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], patch_operations: List[Dict[str, Any]], *, filter_predicate: str | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, no_response: bool | None = None, **kwargs: Any) -> CosmosDict

Parameters

Name	Description
item Required	Union[str, Dict[str, Any]] The ID (name) or dict representing item to be patched.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] The partition key of the object to patch.
patch_operations Required	List[Dict[str, Any]] The list of patch operations to apply to the item.

Keyword-Only Parameters

Name	Description
filter_predicate	str conditional filter to apply to Patch operations.
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.
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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Returns

Type	Description
CosmosDict[str, Any]	A CosmosDict representing the item after the patch operations went through. The dict will be empty if no_response is specified.

Exceptions

Type	Description
CosmosHttpResponseError	The patch operations failed or the item with given id does not exist.

query_conflicts

Return all conflicts matching a given query.

query_conflicts(query: str, *, parameters: List[Dict[str, object]] | None = None, partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue] | None = None, max_item_count: int | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.

Keyword-Only Parameters

Name	Description
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, Sequence[Union[str, int, float, bool, None]]] 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], <xref:AsyncItemPaged>[Dict[str, Any]]], None] A callable invoked with the response metadata.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, Any]]	An AsyncItemPaged of conflicts (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

query_items

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.

query_items(query: str, *, parameters: List[Dict[str, object]] | None = None, partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue] | None = None, max_item_count: int | None = None, enable_scan_in_query: bool | None = None, populate_query_metrics: bool | None = None, populate_index_metrics: bool | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, max_integrated_cache_staleness_in_ms: int | None = None, priority: Literal['High', 'Low'] | None = None, continuation_token_limit: int | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.

Keyword-Only Parameters

Name	Description
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, Sequence[Union[str, int, float, bool, None]]] 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.
populate_index_metrics	bool Used to obtain the index metrics to understand how the query engine used existing indexes and how it could use potential new indexes. Please note that this options will incur overhead, so it should be enabled only when debugging slow queries.
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[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None] A callable invoked with the response metadata.
continuation_token_limit	int The size limit in kb of the response continuation token in the query response. Valid values are positive integers. A value of 0 is the same as not passing a value (default no limit).
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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, Any]]	An AsyncItemPaged of items (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

Examples

Get all products that have not been discontinued:


           import json

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

Parameterized query to get all products that have been discontinued:


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

query_items_change_feed

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

query_items_change_feed(*, max_item_count: int | None = None, start_time: datetime | Literal['Now', 'Beginning'] | None = None, partition_key: PartitionKeyType, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Keyword-Only Parameters

Name	Description
continuation	str The continuation token retrieved from previous response.
feed_range	Dict[str, Any] The feed range that is used to define the scope.
partition_key	The partition key that is used to define the scope (logical partition or a subset of a container)
max_item_count	int Max number of items to be returned in the enumeration operation.
start_time	The start time to start processing chang feed items. Beginning: Processing the change feed items from the beginning of the change feed. Now: Processing change feed from the current time, so only events for all future changes will be retrieved. ~datetime.datetime: processing change feed from a point of time. Provided value will be converted to UTC. By default, it is start from current ("Now")
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, Any]]	An AsyncItemPaged of items (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

read

Read the container properties.

async read(*, populate_partition_key_range_statistics: bool | None = None, populate_quota_info: bool | None = None, session_token: str | None = None, priority: Literal['High', 'Low'] | None = None, initial_headers: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]

Keyword-Only Parameters

Name	Description
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.
initial_headers	dict[str, 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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.

Returns

Type	Description
Dict[str, Any]	Dict representing the retrieved container.

Exceptions

Type	Description
CosmosHttpResponseError	Raised if the container couldn't be retrieved. This includes if the container does not exist.

read_all_items

List all the items in the container.

read_all_items(*, max_item_count: int | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, max_integrated_cache_staleness_in_ms: int | None = None, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Keyword-Only Parameters

Name	Description
max_item_count	int Max number of items to be returned in the enumeration operation.
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[[Dict[str, str], <xref: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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.

Returns

Type	Description
<xref:AsyncItemPaged>[Dict[str, Any]]	An AsyncItemPaged of items (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

read_feed_ranges

Obtains a list of feed ranges that can be used to parallelize feed operations.

Warning

The structure of the dict representation of a feed range may vary, including which keys

are present. It therefore should only be treated as an opaque value.

read_feed_ranges(*, force_refresh: bool = False, **kwargs: Any) -> AsyncIterable[Dict[str, Any]]

Keyword-Only Parameters

Name	Description
force_refresh	bool Flag to indicate whether obtain the list of feed ranges directly from cache or refresh the cache.

Returns

Type	Description
AsyncIterable[Dict[str, Any]]	AsyncIterable representing the feed ranges in base64 encoded string

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

read_item

Get the item identified by item.

async read_item(item: str | Mapping[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], *, post_trigger_include: str | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, max_integrated_cache_staleness_in_ms: int | None = None, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> CosmosDict

Parameters

Name	Description
item Required	Union[str, Dict[str, Any]] The ID (name) or dict representing item to retrieve.
partition_key Required	Union[str, int, float, bool, Sequence[Union[str, int, float, bool, None]]] Partition key for the item to retrieve.

Keyword-Only Parameters

Name	Description
post_trigger_include	str trigger id to be used as post operation trigger.
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[[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.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.

Returns

Type	Description
CosmosDict[str, Any]	A CosmosDict representing the retrieved item.

Exceptions

Type	Description
CosmosHttpResponseError	The given item couldn't be retrieved.

Examples

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


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

replace_item

Replaces the specified item if it exists in the container.

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

async replace_item(item: str | Mapping[str, Any], body: Dict[str, Any], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, no_response: bool | None = None, **kwargs: Any) -> CosmosDict

Parameters

Name	Description
item Required	Union[str, Dict[str, Any]] The ID (name) or dict representing item to be replaced.
body Required	Dict[str, Any] A dict representing the item to replace.

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Returns

Type	Description
CosmosDict[str, Any]	A CosmosDict representing the item after replace went through. The dict will be empty if no_response is specified.

Exceptions

Type	Description
CosmosHttpResponseError	The replace operation failed or the item with given id does not exist.

replace_throughput

Replace the container's throughput.

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

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

Parameters

Name	Description
throughput Required	Union[int, ThroughputProperties] The throughput to be set.

Keyword-Only Parameters

Name	Description
response_hook	Callable[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.

Returns

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

Exceptions

Type	Description
CosmosHttpResponseError	No throughput properties exist for the container or the throughput properties could not be updated.

upsert_item

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.

async upsert_item(body: Dict[str, Any], *, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, session_token: str | None = None, initial_headers: Dict[str, str] | None = None, etag: str | None = None, match_condition: MatchConditions | None = None, priority: Literal['High', 'Low'] | None = None, no_response: bool | None = None, **kwargs: Any) -> CosmosDict

Parameters

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

Keyword-Only Parameters

Name	Description
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.
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[[Dict[str, str], Dict[str, Any]], None] A callable invoked with the response metadata.
priority	Literal["High", "Low"] Priority based execution allows users to set a priority for each request. Once the user has reached their provisioned throughput, low priority requests are throttled before high priority requests start getting throttled. Feature must first be enabled at the account level.
no_response	bool Indicates whether service should be instructed to skip sending response payloads. When not specified explicitly here, the default value will be determined from client-level options.

Returns

Type	Description
CosmosDict[str, Any]	A CosmosDict representing the upserted item. The dict will be empty if no_response is specified.

Exceptions

Type	Description
CosmosHttpResponseError	The given item could not be upserted.

Share via

ContainerProxy Class

Constructor

Parameters

Variables

Methods

create_item

Parameters

Keyword-Only Parameters

Returns

Exceptions

delete_all_items_by_partition_key

Parameters

Keyword-Only Parameters

Returns

Exceptions

delete_conflict

Parameters

Keyword-Only Parameters

Returns

Exceptions

delete_item

Parameters

Keyword-Only Parameters

Returns

Exceptions

execute_item_batch

Parameters

Keyword-Only Parameters

Returns

Exceptions

feed_range_from_partition_key

Parameters

Keyword-Only Parameters

Exceptions

get_conflict

Parameters

Keyword-Only Parameters

Returns

Exceptions

get_latest_session_token

Parameters

Keyword-Only Parameters

Exceptions

get_throughput

Keyword-Only Parameters

Returns

Exceptions

is_feed_range_subset

Parameters

Keyword-Only Parameters

Exceptions

list_conflicts

Keyword-Only Parameters

Returns

Exceptions

patch_item

Parameters

Keyword-Only Parameters

Returns

Exceptions

query_conflicts

Parameters

Keyword-Only Parameters

Returns

Exceptions

query_items

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

query_items_change_feed

Keyword-Only Parameters

Returns

Exceptions

read

Keyword-Only Parameters

Returns

Exceptions