From b3cd6424f142f0147a07136c25ec57fe9e01127a Mon Sep 17 00:00:00 2001 From: Bhuvansh855 Date: Sun, 26 Jul 2026 00:23:55 +0530 Subject: [PATCH] Add integrated cache best practice rule --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .kimi-plugin/plugin.json | 2 +- apm.yml | 2 +- gemini-extension.json | 2 +- package.json | 2 +- plugin.json | 2 +- skills/cosmosdb-best-practices/SKILL.md | 1 + skills/cosmosdb-best-practices/metadata.json | 2 +- .../rules/sdk-connection-mode.md | 3 +- .../rules/throughput-integrated-cache.md | 63 +++++++++++++++++++ 12 files changed, 75 insertions(+), 10 deletions(-) create mode 100644 skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8957a34d..64d8d6b9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "azure-cosmosdb", - "version": "1.2.0", + "version": "1.2.1", "description": "Official Claude plugin for Azure Cosmos DB (NoSQL). Bundles skills for data modeling, partition key design, query optimization, SDK best practices, indexing, vector search, full-text search, global distribution, security, and more.", "author": { "name": "Azure Cosmos DB", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 4e0707b0..d9553af8 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "azure-cosmosdb", - "version": "1.2.0", + "version": "1.2.1", "description": "Official Codex plugin for Azure Cosmos DB (NoSQL). Best practice skills for data modeling, queries, indexing, vector search, security, and more.", "author": { "name": "Azure Cosmos DB", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 00d966fc..a52561d6 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "azure-cosmosdb", - "version": "1.2.0", + "version": "1.2.1", "description": "Official Cursor plugin for Azure Cosmos DB (NoSQL). Best practice skills for data modeling, queries, indexing, vector search, security, and more.", "author": { "name": "Azure Cosmos DB", diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json index 78d26129..765f7bd5 100644 --- a/.kimi-plugin/plugin.json +++ b/.kimi-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "azure-cosmosdb", - "version": "1.2.0", + "version": "1.2.1", "description": "Official Kimi Code plugin for Azure Cosmos DB (NoSQL) with bundled skills and MCP access for data modeling, partition key design, query optimization, SDK best practices, indexing, vector search, full-text search, global distribution, and security.", "author": { "name": "Azure Cosmos DB", diff --git a/apm.yml b/apm.yml index c7e9dcc7..b8e8b712 100644 --- a/apm.yml +++ b/apm.yml @@ -1,5 +1,5 @@ name: cosmosdb-agent-kit -version: 1.2.0 +version: 1.2.1 description: >- Azure Cosmos DB best practices and performance optimization skills for AI coding agents. Provides expert guidance on data modeling, partition key design, query optimization, diff --git a/gemini-extension.json b/gemini-extension.json index 946dd140..fe77be54 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,6 +1,6 @@ { "name": "azure-cosmosdb", - "version": "1.2.0", + "version": "1.2.1", "description": "Official Gemini extension for Azure Cosmos DB (NoSQL). Provides best practice skills for data modeling, partition key design, query optimization, indexing, vector search, full-text search, global distribution, security, and more.", "skills": "./skills/" } diff --git a/package.json b/package.json index 9b0a6437..94331888 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "cosmosdb-agent-kit", - "version": "1.2.0", + "version": "1.2.1", "description": "Azure Cosmos DB best practices for AI coding agents", "keywords": [ "cosmosdb", diff --git a/plugin.json b/plugin.json index 9a975000..f2f42a89 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "cosmosdb", "description": "Azure Cosmos DB best practices and performance optimization skills for AI coding agents. Provides expert guidance on data modeling, partition key design, query optimization, SDK usage, indexing, throughput, global distribution, vector search, and full-text search.", - "version": "1.2.0", + "version": "1.2.1", "author": { "name": "Microsoft", "url": "https://github.com/AzureCosmosDB" diff --git a/skills/cosmosdb-best-practices/SKILL.md b/skills/cosmosdb-best-practices/SKILL.md index e5721181..8cf4bc99 100644 --- a/skills/cosmosdb-best-practices/SKILL.md +++ b/skills/cosmosdb-best-practices/SKILL.md @@ -148,6 +148,7 @@ Reference these guidelines when: - [throughput-burst](rules/throughput-burst.md) - Understand burst capacity - [throughput-container-vs-database](rules/throughput-container-vs-database.md) - Choose allocation level wisely - [throughput-idle-container-review](rules/throughput-idle-container-review.md) - Review idle containers for lifecycle action +- [throughput-integrated-cache](rules/throughput-integrated-cache.md) - Use integrated cache for read-heavy workloads with dedicated gateway - [throughput-ttl-stale-data](rules/throughput-ttl-stale-data.md) - Expire stale data with TTL before hitting storage limits - [throughput-serverless-migration](rules/throughput-serverless-migration.md) - Migrate a low-traffic provisioned account to serverless diff --git a/skills/cosmosdb-best-practices/metadata.json b/skills/cosmosdb-best-practices/metadata.json index 57ca52d6..b220129d 100644 --- a/skills/cosmosdb-best-practices/metadata.json +++ b/skills/cosmosdb-best-practices/metadata.json @@ -1,5 +1,5 @@ { - "version": "1.2.0", + "version": "1.2.1", "organization": "CosmosDB Agent Kit", "date": "January 2026", "abstract": "Performance optimization and best practices guide for Azure Cosmos DB applications, ordered by impact. Contains rules for data modeling, partition key design, query optimization, SDK usage, indexing, throughput management, global distribution, monitoring, developer tooling, and vector search.", diff --git a/skills/cosmosdb-best-practices/rules/sdk-connection-mode.md b/skills/cosmosdb-best-practices/rules/sdk-connection-mode.md index 4d05ea38..b22b2555 100644 --- a/skills/cosmosdb-best-practices/rules/sdk-connection-mode.md +++ b/skills/cosmosdb-best-practices/rules/sdk-connection-mode.md @@ -7,7 +7,7 @@ tags: sdk, connection-mode, direct, performance ## Use Direct Connection Mode for Production -Use Direct connection mode for production workloads. Gateway mode adds an extra network hop and is only needed for firewall-restricted environments. +Use Direct connection mode for production workloads. Gateway mode adds an extra network hop and should generally be avoided unless the workload has a specific requirement for Gateway mode, such as firewall restrictions or Azure Cosmos DB integrated cache (via the dedicated gateway). **Incorrect (defaulting to Gateway mode):** @@ -58,6 +58,7 @@ var gatewayClient = new CosmosClient(connectionString, new CosmosClientOptions // 1. Corporate firewall blocks TCP port range 10000-20000 // 2. Running in Azure Functions Consumption plan (sometimes) // 3. Kubernetes with restrictive network policies + // 4. Using Azure Cosmos DB Integrated Cache, which requires the dedicated gateway endpoint/connection string ConnectionMode = ConnectionMode.Gateway }); ``` diff --git a/skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md b/skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md new file mode 100644 index 00000000..995c7320 --- /dev/null +++ b/skills/cosmosdb-best-practices/rules/throughput-integrated-cache.md @@ -0,0 +1,63 @@ +--- +title: Use Integrated Cache for Read-Heavy Workloads with Dedicated Gateway +impact: MEDIUM +impactDescription: reduces RU consumption and latency for repeated reads +tags: throughput, integrated-cache, dedicated-gateway, performance, cost, read-heavy +--- + +## Use Integrated Cache for Read-Heavy Workloads with Dedicated Gateway + +**Impact: MEDIUM (reduces RU consumption and latency for repeated reads)** + +For workloads that repeatedly read the same items or execute the same queries, Azure Cosmos DB's integrated cache can significantly reduce RU consumption and improve response latency. The integrated cache is available only when using a **dedicated gateway**. Cached point reads and queries can be served without contacting backend replicas until the configured cache staleness window expires. + +Use the `MaxIntegratedCacheStaleness` request option to control how stale cached results are allowed to be. Integrated cache is appropriate for read-heavy workloads where slightly stale data is acceptable, but it only applies to reads using **Session** or **Eventual** consistency. + +**Incorrect (point reads without integrated cache):** + +```csharp +var client = new CosmosClient(connectionString); +var container = client.GetContainer("database", "container"); + +var response = await container.ReadItemAsync( + "product-1", + new PartitionKey("electronics")); +``` + +Every repeated request is sent to the backend, consuming RUs even when the data has not changed. + +**Correct (use dedicated gateway with integrated cache):** + +```csharp +var client = new CosmosClient( + dedicatedGatewayConnectionString, + new CosmosClientOptions + { + ConnectionMode = ConnectionMode.Gateway + }); + +var container = client.GetContainer("database", "container"); + +var options = new ItemRequestOptions +{ + DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions + { + MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(5) + } +}; + +var response = await container.ReadItemAsync( + "product-1", + new PartitionKey("electronics"), + options); +``` + +Guidance: + +- Use integrated cache for read-heavy workloads with frequent repeated point reads or queries. +- Connect through the **dedicated gateway** endpoint to enable integrated cache. +- Configure `MaxIntegratedCacheStaleness` based on how much stale data your application can tolerate. +- Use integrated cache only when **Eventual** or **Session** consistency satisfies application requirements. +- Do not rely on integrated cache for workloads requiring **Strong**, **Bounded Staleness**, or **Consistent Prefix** consistency guarantees. + +Reference: