ContainerProxy Class

Reference

An interface to interact with a specific DB Container.

This class should not be instantiated directly. Instead, use the get_container_client method to get an existing container, or the 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.
container_link	str The URL path of 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.
get_conflict	Get the conflict identified by conflict.
get_throughput	Get the ThroughputProperties object for this container. If no ThroughputProperties already exist for the container, an exception is raised.
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_item	Get the item identified by item.
read_offer	Get the ThroughputProperties object for this container. If no ThroughputProperties already exist for the container, an exception is raised.
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.

create_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, 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, **kwargs: Any) -> Dict[str, Any]

Parameters

Name	Description
body Required	Dict[str, Any] A dict-like object representing the item to create.
pre_trigger_include Required	str trigger id to be used as pre operation trigger.
post_trigger_include Required	str trigger id to be used as post operation trigger.
indexing_directive Required	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.

Keyword-Only Parameters

Name	Description
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 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]	A dict representing the new item.

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.

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, List[Union[str, int, float, bool]]] 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.

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 be deleted.
partition_key Required	Union[str, int, float, bool, List[Union[str, int, float, bool]]] Partition key for the conflict to delete.

Keyword-Only Parameters

Name	Description
response_hook	Callable 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.

delete_item(item: Mapping[str, Any] | str, partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], populate_query_metrics: bool | None = None, 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, List[Union[str, int, float, bool]]] Specifies the partition key value for the item.
pre_trigger_include Required	str trigger id to be used as pre operation trigger.
post_trigger_include Required	str trigger id to be used as post operation trigger.

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

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) -> List[Dict[str, Any]]

Parameters

Name	Description
batch_operations Required	List[Tuple[Any]] The batch of operations to be executed.
partition_key Required	Union[str, int, float, bool, List[Union[str, int, float, bool]]] 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
List[Dict[str, Any]]	A list representing the item after the batch operations went through.

Exceptions

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

get_conflict

Get the conflict identified by conflict.

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, List[Union[str, int, float, bool]]] Partition key for the conflict to retrieve.

Keyword-Only Parameters

Name	Description
response_hook	Callable 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_throughput

Get the ThroughputProperties object for this container.

If no ThroughputProperties already exist for the container, 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	Throughput for the container.

Exceptions

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

list_conflicts

List all the conflicts in the container.

list_conflicts(max_item_count: int | 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
response_hook	Callable A callable invoked with the response metadata.

Returns

Type	Description
Iterable[dict[str, Any]]	An Iterable 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.

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, **kwargs: Any) -> Dict[str, Any]

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, List[Union[str, int, float, bool]]] 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.

Returns

Type	Description
dict[str, Any]	A dict representing the item after the patch operations went through.

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, enable_cross_partition_query: bool | 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) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.
parameters Required	List[Dict[str, object]] Optional array of parameters to the query. Ignored if no query is provided.
enable_cross_partition_query Required	bool Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.
partition_key Required	Union[str, int, float, bool, List[Union[str, int, float, bool]]] Specifies the partition key value for the item.
max_item_count Required	int Max number of items 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 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, enable_cross_partition_query: bool | 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) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
query Required	str The Azure Cosmos DB SQL query to execute.
parameters Required	[List[Dict[str, object]]] 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 Required	Union[str, int, float, bool, List[Union[str, int, float, bool]]] partition key at which the query request is targeted.
enable_cross_partition_query Required	bool Allows sending of more than one request to execute the query in the Azure Cosmos DB service. More than one request is necessary if the query is not scoped to single partition key value.
max_item_count Required	int Max number of items to be returned in the enumeration operation.
enable_scan_in_query Required	bool Allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.
populate_query_metrics Required	bool Enable returning query metrics in response headers.

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

Returns

Type	Description
<xref:ItemPaged>[Dict[str, Any]]	An Iterable 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

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

Parameterized query to get all products that have been discontinued:


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

query_items_change_feed

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

query_items_change_feed(partition_key_range_id: str | None = None, is_start_from_beginning: bool = False, continuation: str | None = None, max_item_count: int | None = None, *, partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue] | None = None, priority: Literal['High', 'Low'] | None = None, **kwargs: Any) -> ItemPaged[Dict[str, Any]]

Parameters

Name	Description
partition_key_range_id Required	str ChangeFeed requests can be executed against specific partition key ranges. This is used to process the change feed in parallel across multiple consumers.
is_start_from_beginning Required	bool Get whether change feed should start from beginning (true) or from current (false). By default, it's start from current (false).
max_item_count Required	int Max number of items to be returned in the enumeration operation.
continuation Required	str e_tag value to be used as continuation for reading change feed.
max_item_count Required	Max number of items to be returned in the enumeration operation.

Keyword-Only Parameters

Name	Description
partition_key	Union[str, int, float, bool, List[Union[str, int, float, bool]]] partition key at which ChangeFeed requests are targeted.
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.

Returns

Type	Description
Iterable[dict[str, Any]]	An Iterable of items (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

read

Read the container properties.

read(populate_query_metrics: bool | None = None, 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]

Parameters

Name	Description
populate_partition_key_range_statistics Required	bool Enable returning partition key range statistics in response headers.
populate_quota_info Required	bool Enable returning collection storage quota information in response headers.

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.
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.
initial_headers	Initial headers to be sent as part of the request.
response_hook	Callable A callable invoked with the response metadata.

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, populate_query_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, **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.
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
Iterable[Dict[str, Any]]	An Iterable of items (dicts).

Exceptions

Type	Description
CosmosHttpResponseError	Item with the given ID already exists.

read_item

Get the item identified by item.

read_item(item: str | Mapping[str, Any], partition_key: str | int | float | bool | Sequence[str | int | float | bool | None] | Type[NonePartitionKeyValue], populate_query_metrics: bool | None = None, 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) -> Dict[str, Any]

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, List[Union[str, int, float, bool]]] Partition key for the item to retrieve.
post_trigger_include Required	str trigger id to be used as post operation trigger.

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.
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
dict[str, Any]	Dict representing the item to be retrieved.

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 = container.read_item("item2", partition_key="Widget")
   item["productModel"] = "DISCONTINUED"
   updated_item = container.upsert_item(item)

read_offer

Get the ThroughputProperties object for this container. If no ThroughputProperties already exist for the container, 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	Throughput for the container.

Exceptions

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

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_item(item: str | Mapping[str, Any], body: Dict[str, Any], populate_query_metrics: bool | None = None, 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) -> Dict[str, Any]

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.
pre_trigger_include Required	str trigger id to be used as pre operation trigger.
post_trigger_include Required	str trigger id to be used as post operation trigger.

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.
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]	A dict representing the item after replace went through.

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.

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

upsert_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, 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) -> Dict[str, Any]

Parameters

Name	Description
body Required	Dict[str, Any] A dict-like object representing the item to update or insert.
pre_trigger_include Required	str trigger id to be used as pre operation trigger.
post_trigger_include Required	str trigger id to be used as post operation trigger.

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.
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]	A dict representing the upserted item.

Exceptions

Type	Description
CosmosHttpResponseError	The given item could not be upserted.