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

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

Exceptions

The conflict wasn't deleted successfully.

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

Exceptions

The item wasn't deleted successfully.

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

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

<xref:azure.cosmos.ThroughputProperties>

Exceptions

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

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

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

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

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

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

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

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

<xref:azure.cosmos.ThroughputProperties>

Exceptions

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

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

<xref:azure.cosmos.ThroughputProperties>

Exceptions

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

The given item could not be upserted.

Attributes

is_system_key

scripts