From 5e8b1f92e58653534e0697269e75d4d24802cb9f Mon Sep 17 00:00:00 2001 From: JericHunter Date: Mon, 25 Jul 2022 11:53:56 -0700 Subject: [PATCH 1/8] Update _container.py --- sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py | 3 --- 1 file changed, 3 deletions(-) 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. From b4074f5e6a9d0a41e72c83825829b0f3482dc144 Mon Sep 17 00:00:00 2001 From: JericHunter Date: Mon, 25 Jul 2022 11:54:01 -0700 Subject: [PATCH 2/8] Update container.py --- sdk/cosmos/azure-cosmos/azure/cosmos/container.py | 3 --- 1 file changed, 3 deletions(-) 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, From 483f526331da7cd4c845a018dc35ced37c11d7db Mon Sep 17 00:00:00 2001 From: JericHunter Date: Mon, 25 Jul 2022 11:54:04 -0700 Subject: [PATCH 3/8] Update CHANGELOG.md --- sdk/cosmos/azure-cosmos/CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/CHANGELOG.md b/sdk/cosmos/azure-cosmos/CHANGELOG.md index 2ec996b0fc5d..04db5156503f 100644 --- a/sdk/cosmos/azure-cosmos/CHANGELOG.md +++ b/sdk/cosmos/azure-cosmos/CHANGELOG.md @@ -48,8 +48,8 @@ Method call will now require an 'id' field to be present in the document body. > for more details on consistency levels, or the README section on this change [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos#note-on-client-consistency-levels). #### 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. +- Added new `max_integrated_cache_staleness_in_ms` parameter to read item and query items APIs in order + to make use of the CosmosDB integrated cache functionality. 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. From 78a058ceb1e7fac837e1324347839f101079b818 Mon Sep 17 00:00:00 2001 From: JericHunter Date: Mon, 25 Jul 2022 12:59:48 -0700 Subject: [PATCH 4/8] Update CHANGELOG.md --- sdk/cosmos/azure-cosmos/CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/CHANGELOG.md b/sdk/cosmos/azure-cosmos/CHANGELOG.md index 04db5156503f..d2218599c99e 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. #### Breaking Changes @@ -48,8 +49,8 @@ Method call will now require an 'id' field to be present in the document body. > for more details on consistency levels, or the README section on this change [here](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cosmos/azure-cosmos#note-on-client-consistency-levels). #### Features Added -- Added new `max_integrated_cache_staleness_in_ms` parameter to read item and query items APIs in order - to make use of the CosmosDB integrated cache functionality. +- 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. 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. From b3f76b6f1779a55a7978e5d83622a5ff5dc39753 Mon Sep 17 00:00:00 2001 From: JericHunter Date: Thu, 28 Jul 2022 11:29:42 -0700 Subject: [PATCH 5/8] Update CHANGELOG.md --- sdk/cosmos/azure-cosmos/CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/CHANGELOG.md b/sdk/cosmos/azure-cosmos/CHANGELOG.md index d2218599c99e..0c247d6f7d07 100644 --- a/sdk/cosmos/azure-cosmos/CHANGELOG.md +++ b/sdk/cosmos/azure-cosmos/CHANGELOG.md @@ -3,7 +3,7 @@ ### 4.3.1 (Unreleased) #### Features Added -- GA release of integrated cache functionality. +- GA release of integrated cache functionality [See PR #25391](https://github.com/Azure/azure-sdk-for-python/pull/25391). #### Breaking Changes @@ -50,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. From 7e32a3fb787d39b75bc6e418bd2d1fbcda3646af Mon Sep 17 00:00:00 2001 From: JericHunter Date: Fri, 29 Jul 2022 13:06:18 -0700 Subject: [PATCH 6/8] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 35 +++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index f79f8f048540..1688d29983cc 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 integrated cache on your Azure Cosmos DB account: [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/en-us/azure/cosmos-db/integrated-cache +[cosmos_configure_integrated_cache]: https://docs.microsoft.com/en-us/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 From 98a8d593963a316fb9a6f972ad42a965c4a9ac58 Mon Sep 17 00:00:00 2001 From: JericHunter Date: Fri, 29 Jul 2022 13:30:49 -0700 Subject: [PATCH 7/8] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 1688d29983cc..c6c911c865ea 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -557,7 +557,7 @@ An integrated cache is an in-memory cache that helps you ensure manageable costs 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 integrated cache on your Azure Cosmos DB account: [How to configure the Azure Cosmos DB integrated cache (Preview)][cosmos_configure_integrated_cache] +[How to configure the Azure Cosmos DB integrated cache (Preview)][cosmos_configure_integrated_cache] ```Python import azure.cosmos.cosmos_client as cosmos_client From 02185fc56508fbbaa05ac50ee989d292f878d984 Mon Sep 17 00:00:00 2001 From: JericHunter Date: Fri, 29 Jul 2022 13:32:17 -0700 Subject: [PATCH 8/8] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index c6c911c865ea..b268be300b7c 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -657,8 +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/en-us/azure/cosmos-db/integrated-cache -[cosmos_configure_integrated_cache]: https://docs.microsoft.com/en-us/azure/cosmos-db/how-to-configure-integrated-cache +[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