ContainerProxy Class

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: azure.cosmos._cosmos_client_connection.CosmosClientConnection, database_link: str, id: str, properties: Optional[Dict[str, Any]] = None)

Parameters

client_connection

database_link

id

properties

default value: None

Variables

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_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.
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. :keyword Callable response_hook: A callable invoked with the response metadata. :returns: Throughput for the container. :raises ~azure.cosmos.exceptions.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.
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. Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.
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. Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.
read_item	Get the item identified by item. Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.
read_offer	Get the ThroughputProperties object for this container. If no ThroughputProperties already exist for the container, an exception is raised. :keyword Callable response_hook: A callable invoked with the response metadata. :returns: Throughput for the container. :raises ~azure.cosmos.exceptions.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_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: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, indexing_directive: Optional[Any] = None, **kwargs: Any) -> Dict[str, Any]

Parameters

body

Required

A dict-like object representing the item to create.

pre_trigger_include

Required

trigger id to be used as pre operation trigger.

post_trigger_include

Required

trigger id to be used as post operation trigger.

indexing_directive

Required

Indicate whether the document should be omitted from indexing.

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[<xref: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

<xref:Callable>

A callable invoked with the response metadata.

Returns

A dict representing the new item.

Return type

dict[str, <xref:Any>]

Exceptions

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

Parameters

conflict

Required

The ID (name) or dict representing the conflict to be deleted.

partition_key

Required

Partition key for the conflict to delete.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Return type

None

Exceptions

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: Union[Dict[str, Any], str], partition_key: Any, populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) -> None

Parameters

item

Required

The ID (name) or dict representing item to be deleted.

partition_key

Required

Specifies the partition key value for the item.

pre_trigger_include

Required

trigger id to be used as pre operation trigger.

post_trigger_include

Required

trigger id to be used as post operation trigger.

session_token

str

Token for use with Session consistency.

initial_headers

dict[<xref: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

<xref:Callable>

A callable invoked with the response metadata.

Return type

None

Exceptions

CosmosHttpResponseError

The item wasn't deleted successfully.

CosmosResourceNotFoundError

The item does not exist in the container.

get_conflict

Get the conflict identified by conflict.

get_conflict(conflict: Union[str, Dict[str, Any]], partition_key: Any, **kwargs: Any) -> Dict[str, Any]

Parameters

conflict

Required

The ID (name) or dict representing the conflict to retrieve.

partition_key

Required

Partition key for the conflict to retrieve.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

A dict representing the retrieved conflict.

Return type

dict[str, <xref:Any>]

Exceptions

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. :keyword Callable response_hook: A callable invoked with the response metadata. :returns: Throughput for the container. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No throughput properties exists for the container or

the throughput properties could not be retrieved.

get_throughput(**kwargs: Any) -> azure.cosmos.offer.ThroughputProperties

Return type

ThroughputProperties

Exceptions

CosmosHttpResponseError

Item with the given ID already exists.

list_conflicts

List all the conflicts in the container.

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

Parameters

max_item_count

Required

Max number of items to be returned in the enumeration operation.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

<xref:Iterable>[dict[str, <xref:Any>]]

Exceptions

CosmosHttpResponseError

Item with the given ID already exists.

query_conflicts

Return all conflicts matching a given query.

query_conflicts(query: str, parameters: Optional[List[str]] = None, enable_cross_partition_query: Optional[bool] = None, partition_key: Optional[Any] = None, max_item_count: Optional[int] = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parameters

query

Required

The Azure Cosmos DB SQL query to execute.

parameters

Required

Optional array of parameters to the query. Ignored if no query is provided.

enable_cross_partition_query

Required

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

Specifies the partition key value for the item.

max_item_count

Required

Max number of items to be returned in the enumeration operation.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

An Iterable of conflicts (dicts).

Return type

<xref:Iterable>[dict[str, <xref:Any>]]

Exceptions

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.

Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.

query_items(query: str, parameters: Optional[List[Dict[str, object]]] = None, partition_key: Optional[Any] = None, enable_cross_partition_query: Optional[bool] = None, max_item_count: Optional[int] = None, enable_scan_in_query: Optional[bool] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Returns

An Iterable of items (dicts).

Return type

<xref:ItemPaged>[<xref:Dict>[str, <xref:Any>]]

Exceptions

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: Optional[str] = None, is_start_from_beginning: bool = False, continuation: Optional[str] = None, max_item_count: Optional[int] = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parameters

partition_key_range_id

Required

ChangeFeed requests can be executed against specific partition key ranges. This is used to process the change feed in parallel across multiple consumers.

partition_key

Required

partition key at which ChangeFeed requests are targetted.

is_start_from_beginning

Required

Get whether change feed should start from beginning (true) or from current (false). By default it's start from current (false).

continuation

Required

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.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

An Iterable of items (dicts).

Return type

<xref:Iterable>[dict[str, <xref:Any>]]

Exceptions

CosmosHttpResponseError

Item with the given ID already exists.

read

Read the container properties.

read(*, populate_partition_key_range_statistics: Optional[bool] = 'None', populate_quota_info: Optional[bool] = 'None', **kwargs)

Parameters

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[<xref:str,str>]

Initial headers to be sent as part of the request.

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

Dict representing the retrieved container.

Return type

dict[str, <xref:Any>]

Exceptions

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.

Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.

read_all_items(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Returns

An Iterable of items (dicts).

Return type

<xref:Iterable>[dict[str, <xref:Any>]]

Exceptions

CosmosHttpResponseError

Item with the given ID already exists.

read_item

Get the item identified by item.

Provisional keyword argument max_integrated_cache_staleness_in_ms :keyword int max_integrated_cache_staleness_in_ms: 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.

read_item(item: Union[str, Dict[str, Any]], partition_key: Any, populate_query_metrics: Optional[bool] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]

Returns

Dict representing the item to be retrieved.

Return type

dict[str, <xref:Any>]

Exceptions

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. :keyword Callable response_hook: A callable invoked with the response metadata. :returns: Throughput for the container. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: No throughput properties exists for the container or

the throughput properties could not be retrieved.

read_offer(**kwargs: Any) -> Offer

Return type

ThroughputProperties

Exceptions

CosmosHttpResponseError

Item with the given ID already exists.

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: Union[str, Dict[str, Any]], body: Dict[str, Any], populate_query_metrics: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]

Parameters

item

Required

The ID (name) or dict representing item to be replaced.

body

Required

A dict-like object representing the item to replace.

pre_trigger_include

Required

trigger id to be used as pre operation trigger.

post_trigger_include

Required

trigger id to be used as post operation trigger.

session_token

str

Token for use with Session consistency.

initial_headers

dict[<xref: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

<xref:Callable>

A callable invoked with the response metadata.

Returns

A dict representing the item after replace went through.

Return type

dict[str, <xref:Any>]

Exceptions

CosmosHttpResponseError

The replace 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, **kwargs: Any) -> azure.cosmos.offer.ThroughputProperties

Parameters

throughput

Required

The throughput to be set (an integer).

response_hook

<xref:Callable>

A callable invoked with the response metadata.

Returns

ThroughputProperties for the container, updated with new throughput.

Return type

ThroughputProperties

Exceptions

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: Optional[bool] = None, pre_trigger_include: Optional[str] = None, post_trigger_include: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]

Parameters

body

Required

A dict-like object representing the item to update or insert.

pre_trigger_include

Required

trigger id to be used as pre operation trigger.

post_trigger_include

Required

trigger id to be used as post operation trigger.

session_token

str

Token for use with Session consistency.

initial_headers

dict[<xref: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

<xref:Callable>

A callable invoked with the response metadata.

Returns

A dict representing the upserted item.

Return type

dict[str, <xref:Any>]

Exceptions

CosmosHttpResponseError

The given item could not be upserted.

Attributes

is_system_key

scripts