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 <xref:Database.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.objectContainerProxy
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
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. |
| 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. |
| 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 |
Read the Offer object for this container. If no Offer already exists 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 Offer already exists 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, str]Parameters
- body
A dict-like object representing the item to create.
- populate_query_metrics
Enable returning query metrics in response headers.
- pre_trigger_include
trigger id to be used as pre operation trigger.
- post_trigger_include
trigger id to be used as post operation trigger.
- indexing_directive
Indicate whether the document should be omitted from indexing.
- 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
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) -> NoneParameters
- conflict
The ID (name) or dict representing the conflict to be deleted.
- partition_key
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) -> NoneParameters
- item
The ID (name) or dict representing item to be deleted.
- partition_key
Specifies the partition key value for the item.
- populate_query_metrics
Enable returning query metrics in response headers.
- pre_trigger_include
trigger id to be used as pre operation trigger.
- post_trigger_include
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, str]Parameters
- conflict
The ID (name) or dict representing the conflict to retrieve.
- partition_key
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
Exceptions
The given conflict couldn't be retrieved.
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
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
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
The Azure Cosmos DB SQL query to execute.
- parameters
Optional array of parameters to the query. Ignored if no query is provided.
- enable_cross_partition_query
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
Specifies the partition key value for the item.
- max_item_count
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
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.
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]]Parameters
- query
The Azure Cosmos DB SQL query to execute.
- parameters
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
Specifies the partition key value for the item.
- enable_cross_partition_query
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
Max number of items to be returned in the enumeration operation.
- enable_scan_in_query
Allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.
- populate_query_metrics
Enable returning query metrics 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
An Iterable of items (dicts).
Return type
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
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
partition key at which ChangeFeed requests are targetted.
- is_start_from_beginning
Get whether change feed should start from beginning (true) or from current (false). By default it's start from current (false).
- continuation
e_tag value to be used as continuation for reading change feed.
- max_item_count
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
Exceptions
Item with the given ID already exists.
read
Read the container properties.
read(populate_query_metrics: Optional[bool] = None, populate_partition_key_range_statistics: Optional[bool] = None, populate_quota_info: Optional[bool] = None, **kwargs: Any) -> Dict[str, Any]Parameters
- populate_query_metrics
Enable returning query metrics in response headers.
- populate_partition_key_range_statistics
Enable returning partition key range statistics in response headers.
- populate_quota_info
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
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.
read_all_items(max_item_count: Optional[int] = None, populate_query_metrics: Optional[bool] = None, **kwargs: Any) -> Iterable[Dict[str, Any]]Parameters
- max_item_count
Max number of items to be returned in the enumeration operation.
- populate_query_metrics
Enable returning query metrics 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
An Iterable of items (dicts).
Return type
Exceptions
Item with the given ID already exists.
read_item
Get the item identified by item.
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, str]Parameters
- item
The ID (name) or dict representing item to retrieve.
- partition_key
Partition key for the item to retrieve.
- populate_query_metrics
Enable returning query metrics in response headers.
- post_trigger_include
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.
- response_hook
- <xref:Callable>
A callable invoked with the response metadata.
Returns
Dict representing the item to be retrieved.
Return type
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
Read the Offer object for this container.
If no Offer already exists for the container, an exception is raised.
read_offer(**kwargs: Any) -> azure.cosmos.offer.OfferParameters
- response_hook
- <xref:Callable>
A callable invoked with the response metadata.
Returns
Offer for the container.
Return type
Exceptions
No offer exists for the container or the offer 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: 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, str]Parameters
- item
The ID (name) or dict representing item to be replaced.
- body
A dict-like object representing the item to replace.
- populate_query_metrics
Enable returning query metrics in response headers.
- pre_trigger_include
trigger id to be used as pre operation trigger.
- post_trigger_include
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
Exceptions
The replace failed or the item with given id does not exist.
replace_throughput
Replace the container's throughput.
If no Offer already exists for the container, an exception is raised.
replace_throughput(throughput: int, **kwargs: Any) -> azure.cosmos.offer.OfferParameters
- throughput
The throughput to be set (an integer).
- response_hook
- <xref:Callable>
A callable invoked with the response metadata.
Returns
Offer for the container, updated with new throughput.
Return type
Exceptions
No offer exists for the container or the offer 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, str]Parameters
- body
A dict-like object representing the item to update or insert.
- populate_query_metrics
Enable returning query metrics in response headers.
- pre_trigger_include
trigger id to be used as pre operation trigger.
- post_trigger_include
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
Exceptions
The given item could not be upserted.
Attributes
is_system_key
scripts
الملاحظات
إرسال الملاحظات وعرضها المتعلقة بـ