Name: cosmosdb-best-practices
Author: azurecosmosdb

Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage. Use when writing, reviewing, or refactoring code that interacts with Azure Cosmos DB, designing data models, optimizing queries, or implementing high-performance database operation

Azure Cosmos DB Best Practices Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 100+ rules across 13 categories, prioritized by impact to guide automated refactoring and code generation. Before answering, read the linked rule files relevant to the user's question. The quick reference below is an index, not the full guidance: SDK APIs, limits, configuration prerequisites, and caveats live in the rule bodies. Use the language specific integration rule when one exists rather than substituting a generic pattern. Keep answers concise, but include the constraints that make the recommendation correct for the user's scenario. When to Apply Reference these guidelines when: Designing data models for Cosmos DB Choosing partition keys Writing or optimizing queries Implementing SDK patterns Using the Cosmos DB Emulator for local development Inspecting or managing Cosmos DB data with developer tooling Implementing vector search or RAG features on Cosmos DB Reviewing code for performance issues Configuring throughput and scaling Building globally distributed applications Rule Categories by Priority Priority Category Impact Prefix 1 Data Modeling CRITICAL model 2 Partition Key Design CRITICAL partition 3 Query Optimization HIGH query 4 SDK Best Practices HIGH sdk 5 Indexing Strategies MEDIUM HIGH index 6 Throughput & Scaling MEDIUM throughput 7 Global Distribution MEDIUM global 8 Monitoring & Diagnostics LOW MEDIUM monitoring 9 Design Patterns HIGH pattern 10 Developer Tooling MEDIUM tooling 11 Vector Search HIGH vector 12 Full Text Search HIGH fts 13 Security HIGH security Quick Reference 1. Data Modeling (CRITICAL) [model embed related](rules/model embed related.md) Embed related data retrieved together [model reference large](rules/model reference large.md) Reference data when items get too large [model avoid 2mb limit](rules/model avoid 2mb limit.md) Keep items well under 2MB limit [model id constraints](rules/model id constraints.md) Follow ID value length and character constraints [model unique keys](rules/model unique keys.md) Enforce business key uniqueness within the correct logical partition scope [model nesting depth](rules/model nesting depth.md) Stay within 128 level nesting depth limit [model numeric precision](rules/model numeric precision.md) Understand IEEE 754 numeric precision limits [model denormalize reads](rules/model denormalize reads.md) Denormalize for read heavy workloads including pre computed aggregates [model schema versioning](rules/model schema versioning.md) Version your document schemas [model type discriminator](rules/model type discriminator.md) Use type discriminators for polymorphic data [model json serialization](rules/model json serialization.md) Handle JSON serialization correctly for Cosmos DB documents [model relationship references](rules/model relationship references.md) Use ID references with transient hydration for document relationships [model ttl expiration](rules/model ttl expiration.md) Configure TTL relative to the item's last update, with container defaults and item overrides 2. Partition Key Design (CRITICAL) [partition high cardinality](rules/partition high cardinality.md) Choose high cardinality partition keys [partition avoid hotspots](rules/partition avoid hotspots.md) Distribute writes evenly [partition hierarchical](rules/partition hierarchical.md) Use hierarchical partition keys for flexibility; order levels broad→narrow [partition query patterns](rules/partition query patterns.md) Align partition key with query patterns [partition synthetic keys](rules/partition synthetic keys.md) Create synthetic keys when needed [partition key length](rules/partition key length.md) Respect partition key value length limits [partition immutable key](rules/partition immutable key.md) Choose immutable properties as partition keys [partition 20gb limit](rules/partition 20gb limit.md) Plan for 20GB logical partition limit [partition rekey migration](rules/partition rekey migration.md) Re key a misaligned container with the Change partition key feature 3. Query Optimization (HIGH) [query aggregate single pass](rules/query aggregate single pass.md) Compute min/max/avg with one scoped aggregate query [query avoid cross partition](rules/query avoid cross partition.md) Minimize cross partition queries [query use projections](rules/query use projections.md) Project only needed fields; prefer dedicated result types for projections [query pagination](rules/query pagination.md) Use continuation tokens for pagination [query avoid scans](rules/query avoid scans.md) Avoid full container scans [query parameterize](rules/query parameterize.md) Use parameterized queries [query order filters](rules/query order filters.md) Let the query engine order filters; tune indexed predicates rather than their textual order [query top literal](rules/query top literal.md) Use literal integers for TOP, never parameters [query latest by timestamp](rules/query latest by timestamp.md) Query "latest" documents with explicit ORDER BY and TOP 1 [query olap detection](rules/query olap detection.md) Detect and redirect analytical queries away from transactional containers [query point reads](rules/query point reads.md) Use point reads (ReadItem) instead of queries when id and partition key are known [query distinct keyword](rules/query distinct keyword.md) Return unique values with DISTINCT instead of client side deduplication 4. SDK Best Practices (HIGH) [sdk singleton client](rules/sdk singleton client.md) Reuse CosmosClient as singleton [sdk async api](rules/sdk async api.md) Use async APIs for throughput [sdk retry 429](rules/sdk retry 429.md) Handle 429s with retry after [sdk connection mode](rules/sdk connection mode.md) Use Direct mode for production [sdk preferred regions](rules/sdk preferred regions.md) Configure preferred regions [sdk excluded regions](rules/sdk excluded regions.md) Exclude regions experiencing issues [sdk availability strategy](rules/sdk availability strategy.md) Configure availability strategy for resilience [sdk circuit breaker](rules/sdk circuit breaker.md) Use circuit breaker for fault tolerance [sdk diagnostics](rules/sdk diagnostics.md) Log diagnostics for troubleshooting [sdk serialization enums](rules/sdk serialization enums.md) Serialize enums as strings not integers [sdk emulator ssl](rules/sdk emulator ssl.md) Configure SSL and connection mode for Cosmos DB Emulator [sdk ifnonematch create](rules/sdk conditional create etag.md) Use setIfNoneMatchETag(" ") on createItem to reject duplicates atomically (409 on conflict) [sdk no shared request options](rules/sdk request options per call.md) Use separate CosmosItemRequestOptions instances for deferred or concurrent createItem operations to avoid shared state partition key overrides [sdk patch incr](rules/sdk patch counter increment.md) Use CosmosPatchOperations.increment() for atomic counter increments — no read RU, no ETag conflict cycle [sdk bypage empty token](rules/sdk continuation token null guard.md) Guard against empty string continuation tokens before calling byPage() — pass null for first page, never "" [sdk etag concurrency](rules/sdk etag concurrency.md) Use ETags for optimistic concurrency on read modify write operations [sdk java content response](rules/sdk java content response.md) Enable content response on write operations (Java) [sdk java cosmos config](rules/sdk java cosmos config.md) Configure Cosmos DB initialization correctly in Spring Boot [sdk java spring boot versions](rules/sdk java spring boot versions.md) Match Java version to Spring Boot requirements [sdk local dev config](rules/sdk local dev config.md) Configure local development to avoid cloud conflicts [sdk dotnet cosmos package id](rules/sdk dotnet cosmos package id.md) Use Microsoft.Azure.Cosmos , not the abandoned Azure.Cosmos v4 preview package [sdk newtonsoft dependency](rules/sdk newtonsoft dependency.md) Explicitly reference Newtonsoft.Json package [sdk python async deps](rules/sdk python async deps.md) Include aiohttp when using Python async SDK [sdk spring data annotations](rules/sdk spring data annotations.md) Annotate entities for Spring Data Cosmos [sdk spring data repository](rules/sdk spring data repository.md) Use CosmosRepository correctly and handle Iterable return types [sdk langchain cosmosdb saver](rules/sdk langchain cosmosdb saver.md) Use CosmosDBSaver for LangGraph checkpointing with async container client [sdk langchain async checkpointer](rules/sdk langchain async checkpointer.md) Initialize async Cosmos DB container in startup routine, not module level [sdk langchain mcp persistent session](rules/sdk langchain mcp persistent session.md) Maintain persistent MCP client sessions for application lifetime [sdk langchain mcp tool content format](rules/sdk langchain mcp tool content format.md) Handle both string and list formats in MCP ToolMessage content [sdk langgraph mcp tool filtering](rules/sdk langgraph mcp tool filtering.md) Filter MCP tools by name prefix for per agent assignment [sdk dotnet namespace collision](rules/sdk dotnet namespace collision.md) Avoid Microsoft.Azure.Cosmos namespace collisions with domain models (User, Database, Container, etc.) [sdk ingestion rate control](rules/sdk ingestion rate control.md) Rate control high volume ingestion (concurrency, retry after, throughput control) [sdk go partition key metadata](rules/sdk go partition key metadata.md) Upgrade stale Go SDKs to serialize partition key kind metadata correctly across SDKs [sdk python client kwargs](rules/sdk python client kwargs.md) Configure Python v4 clients with flat keyword arguments instead of legacy ConnectionPolicy objects [sdk langchain js chat history](rules/sdk langchain js chat history.md) Persist isolated JS/TS conversations with AzureCosmosDBNoSQLChatMessageHistory [sdk langchain js embedding model](rules/sdk langchain js embedding model.md) Configure the Azure OpenAI deployment name for JS/TS embeddings [sdk langchain js filter injection](rules/sdk langchain js filter injection.md) Bind vector store filter values through a parameterized filterClause [sdk langchain js fulltext prerequisites](rules/sdk langchain js fulltext prerequisites.md) Configure account capability, text policy, and indexes before hybrid search [sdk langchain js managed identity](rules/sdk langchain js managed identity.md) Authenticate JS/TS LangChain with managed identity and data plane RBAC [sdk langchain js search types](rules/sdk langchain js search types.md) Choose vector, full text, or hybrid retrieval for the query [sdk langchain js semantic cache](rules/sdk langchain js semantic cache.md) Reuse equivalent LLM responses with AzureCosmosDBNoSQLSemanticCache [sdk langchain js vectorstore init](rules/sdk langchain js vectorstore init.md) Initialize JS/TS vector stores with embeddings and pre provisioned RBAC resources 5. Indexing Strategies (MEDIUM HIGH) [index exclude unused](rules/index exclude unused.md) Exclude paths never queried [index path syntax](rules/index path syntax.md) Use correct path notation ( /? , /[] , / ) [index composite](rules/index composite.md) Use composite indexes for ORDER BY [index composite direction](rules/index composite direction.md) Match composite index directions to ORDER BY [index spatial](rules/index spatial.md) Add spatial indexes for geo queries [index range vs hash](rules/index range