diff --git a/sdk/cosmos/azure-cosmos/CHANGELOG.md b/sdk/cosmos/azure-cosmos/CHANGELOG.md index 2ec996b0fc5d..0c247d6f7d07 100644 --- a/sdk/cosmos/azure-cosmos/CHANGELOG.md +++ b/sdk/cosmos/azure-cosmos/CHANGELOG.md @@ -3,6 +3,7 @@ ### 4.3.1 (Unreleased) #### Features Added +- GA release of integrated cache functionality [See PR #25391](https://github.com/Azure/azure-sdk-for-python/pull/25391). #### Breaking Changes @@ -49,7 +50,7 @@ Method call will now require an 'id' field to be present in the document body. #### Features Added - Added new **provisional** `max_integrated_cache_staleness_in_ms` parameter to read item and query items APIs in order - to make use of the **preview** CosmosDB integrated cache functionality. + to make use of the **preview** CosmosDB integrated cache functionality [See PR #22946](https://github.com/Azure/azure-sdk-for-python/pull/22946). Please see [Azure Cosmos DB integrated cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache) for more details. - Added support for split-proof queries for the async client. diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index f79f8f048540..b268be300b7c 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -551,6 +551,39 @@ async def create_lists(): item_list = [item async for item in results] await client.close() ``` + +### Using Integrated Cache +An integrated cache is an in-memory cache that helps you ensure manageable costs and low latency as your request volume grows. The integrated cache has two parts: an item cache for point reads and a query cache for queries. The code snippet below shows you how to use this feature with the point read and query cache methods. + +The benefit of using this is that the point reads and queries that hit the integrated cache won't use any RUs. This means you will have a much lower per-operation cost than reads from the backend. + +[How to configure the Azure Cosmos DB integrated cache (Preview)][cosmos_configure_integrated_cache] + +```Python +import azure.cosmos.cosmos_client as cosmos_client +import os + +URL = os.environ['ACCOUNT_URI'] +KEY = os.environ['ACCOUNT_KEY'] +client = cosmos_client.CosmosClient(URL, credential=KEY) +DATABASE_NAME = 'testDatabase' +database = client.get_database_client(DATABASE_NAME) +CONTAINER_NAME = 'testContainer' +container = database.get_container_client(CONTAINER_NAME) + +def integrated_cache_snippet(): + item_id = body['id'] + query = 'SELECT * FROM c' + + #item cache + container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000) + + #query cache + container.query_items(query=query, + partition_key=item_id, max_integrated_cache_staleness_in_ms=30000) +``` +For more information on Integrated Cache, see [Azure Cosmos DB integrated cache - Overview][cosmos_integrated_cache]. + ## Troubleshooting ### General @@ -624,6 +657,8 @@ For more extensive documentation on the Cosmos DB service, see the [Azure Cosmos [cosmos_resources]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items [cosmos_sql_queries]: https://docs.microsoft.com/azure/cosmos-db/how-to-sql-query [cosmos_ttl]: https://docs.microsoft.com/azure/cosmos-db/time-to-live +[cosmos_integrated_cache]: https://docs.microsoft.com/azure/cosmos-db/integrated-cache +[cosmos_configure_integrated_cache]: https://docs.microsoft.com/azure/cosmos-db/how-to-configure-integrated-cache [python]: https://www.python.org/downloads/ [ref_container_delete_item]: https://aka.ms/azsdk-python-cosmos-ref-delete-item [ref_container_query_items]: https://aka.ms/azsdk-python-cosmos-ref-query-items diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py index d9d67adddeea..53d1f80f39b4 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py @@ -218,7 +218,6 @@ async def read_item( :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request. :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], Dict[str, Any]], None] - **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. @@ -265,7 +264,6 @@ def read_all_items( :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request. :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None] - **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. @@ -321,7 +319,6 @@ def query_items( :keyword dict[str, str] initial_headers: Initial headers to be sent as part of the request. :keyword response_hook: A callable invoked with the response metadata. :paramtype response_hook: Callable[[Dict[str, str], AsyncItemPaged[Dict[str, Any]]], None] - **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. diff --git a/sdk/cosmos/azure-cosmos/azure/cosmos/container.py b/sdk/cosmos/azure-cosmos/azure/cosmos/container.py index 6be5d17c8561..a02b2bb5c419 100644 --- a/sdk/cosmos/azure-cosmos/azure/cosmos/container.py +++ b/sdk/cosmos/azure-cosmos/azure/cosmos/container.py @@ -185,7 +185,6 @@ def read_item( :keyword str session_token: Token for use with Session consistency. :keyword dict[str,str] initial_headers: Initial headers to be sent as part of the request. :keyword Callable response_hook: A callable invoked with the response metadata. - **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, @@ -242,7 +241,6 @@ def read_all_items( :keyword str session_token: Token for use with Session consistency. :keyword dict[str,str] initial_headers: Initial headers to be sent as part of the request. :keyword Callable response_hook: A callable invoked with the response metadata. - **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, @@ -357,7 +355,6 @@ def query_items( :keyword str session_token: Token for use with Session consistency. :keyword dict[str,str] initial_headers: Initial headers to be sent as part of the request. :keyword Callable response_hook: A callable invoked with the response metadata. - **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,