Azure Cosmos DB Best Practices

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 75+ rules across 11 categories, prioritized by impact to guide automated refactoring and code generation.

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

Quick Reference

1. Data Modeling (CRITICAL)

• model-embed-related - Embed related data retrieved together
• model-reference-large - Reference data when items get too large
• model-avoid-2mb-limit - Keep items well under 2MB limit
• model-id-constraints - Follow ID value length and character constraints
• model-nesting-depth - Stay within 128-level nesting depth limit
• model-numeric-precision - Understand IEEE 754 numeric precision limits
• model-denormalize-reads - Denormalize for read-heavy workloads including pre-computed aggregates
• model-schema-versioning - Version your document schemas
• model-type-discriminator - Use type discriminators for polymorphic data
• model-json-serialization - Handle JSON serialization correctly for Cosmos DB documents
• model-relationship-references - Use ID references with transient hydration for document relationships

2. Partition Key Design (CRITICAL)

• partition-high-cardinality - Choose high-cardinality partition keys
• partition-avoid-hotspots - Distribute writes evenly
• partition-hierarchical - Use hierarchical partition keys for flexibility; order levels broad→narrow
• partition-query-patterns - Align partition key with query patterns
• partition-synthetic-keys - Create synthetic keys when needed
• partition-key-length - Respect partition key value length limits
• partition-immutable-key - Choose immutable properties as partition keys
• partition-20gb-limit - Plan for 20GB logical partition limit

3. Query Optimization (HIGH)

• query-avoid-cross-partition - Minimize cross-partition queries
• query-use-projections - Project only needed fields; prefer dedicated result types for projections
• query-pagination - Use continuation tokens for pagination
• query-avoid-scans - Avoid full container scans
• query-parameterize - Use parameterized queries
• query-order-filters - Order filters by selectivity
• query-top-literal - Use literal integers for TOP, never parameters
• query-olap-detection - Detect and redirect analytical queries away from transactional containers
• query-point-reads - Use point reads (ReadItem) instead of queries when id and partition key are known

4. SDK Best Practices (HIGH)

• sdk-singleton-client - Reuse CosmosClient as singleton
• sdk-async-api - Use async APIs for throughput
• sdk-retry-429 - Handle 429s with retry-after
• sdk-connection-mode - Use Direct mode for production
• sdk-preferred-regions - Configure preferred regions
• sdk-excluded-regions - Exclude regions experiencing issues
• sdk-availability-strategy - Configure availability strategy for resilience
• sdk-circuit-breaker - Use circuit breaker for fault tolerance
• sdk-diagnostics - Log diagnostics for troubleshooting
• sdk-serialization-enums - Serialize enums as strings not integers
• sdk-emulator-ssl - Configure SSL and connection mode for Cosmos DB Emulator
• sdk-ifnonematch-create - Use setIfNoneMatchETag("*") on createItem to reject duplicates atomically (409 on conflict)
• sdk-no-shared-request-options - Never reuse a CosmosItemRequestOptions instance across multiple createItem calls — SDK mutates it internally, causing wrong partition key on second call
• sdk-patch-incr - Use CosmosPatchOperations.incr() for atomic counter increments — no read RU, no ETag conflict cycle
• sdk-bypage-empty-token - Guard against empty-string continuation tokens before calling byPage() — pass null for first page, never ""
• sdk-etag-concurrency - Use ETags for optimistic concurrency on read-modify-write operations
• sdk-java-content-response - Enable content response on write operations (Java)
• sdk-java-cosmos-config - Configure Cosmos DB initialization correctly in Spring Boot
• sdk-java-spring-boot-versions - Match Java version to Spring Boot requirements
• sdk-local-dev-config - Configure local development to avoid cloud conflicts
• sdk-newtonsoft-dependency - Explicitly reference Newtonsoft.Json package
• sdk-python-async-deps - Include aiohttp when using Python async SDK
• sdk-spring-data-annotations - Annotate entities for Spring Data Cosmos
• sdk-spring-data-repository - Use CosmosRepository correctly and handle Iterable return types

5. Indexing Strategies (MEDIUM-HIGH)

• index-exclude-unused - Exclude paths never queried
• index-composite - Use composite indexes for ORDER BY
• index-composite-direction - Match composite index directions to ORDER BY
• index-spatial - Add spatial indexes for geo queries
• index-range-vs-hash - Choose appropriate index types
• index-lazy-consistent - Understand indexing modes

6. Throughput & Scaling (MEDIUM)

• throughput-autoscale - Use autoscale for variable workloads
• throughput-right-size - Right-size provisioned throughput
• throughput-serverless - Consider serverless for dev/test
• throughput-burst - Understand burst capacity
• throughput-container-vs-database - Choose allocation level wisely

7. Global Distribution (MEDIUM)

• global-multi-region - Configure multi-region writes
• global-consistency - Choose appropriate consistency level
• global-conflict-resolution - Implement conflict resolution
• global-failover - Configure automatic failover
• global-read-regions - Add read regions near users
• global-zone-redundancy - Enable zone redundancy for HA

8. Monitoring & Diagnostics (LOW-MEDIUM)

• monitoring-ru-consumption - Track RU consumption
• monitoring-latency - Monitor P99 latency
• monitoring-throttling - Alert on throttling
• monitoring-azure-monitor - Integrate Azure Monitor
• monitoring-diagnostic-logs - Enable diagnostic logging

9. Design Patterns (HIGH)

• pattern-change-feed-materialized-views - Use Change Feed for cross-partition query optimization
• pattern-efficient-ranking - Use count-based or cached approaches for efficient ranking
• pattern-service-layer-relationships - Use a service layer to hydrate document references

10. Developer Tooling (MEDIUM)

• tooling-vscode-extension - Use the VS Code extension for routine inspection and management
• tooling-emulator-setup - Use the Emulator for local development and testing

11. Vector Search (HIGH)

• vector-enable-feature - Enable vector search on the account before using vector features
• how to use cosmosdb-best-practices
  CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity

  How to use cosmosdb-best-practices on Cursor

  AI-first code editor with Composer

  1

  Prerequisites

  Before installing skills in Cursor, ensure your development environment meets these requirements:

  • ›Cursor installed and configured on your development machine
  • ›Node.js version 16.0+ with npm package manager (verify with node --version)
  • ›Active project directory or workspace where you want to add cosmosdb-best-practices

  2

  Execute installation command

  Execute the skills CLI command in your project's root directory to begin installation:

  $npx skills add https://github.com/azurecosmosdb/cosmosdb-agent-kit --skill cosmosdb-best-practicescopy

  The skills CLI fetches cosmosdb-best-practices from GitHub repository azurecosmosdb/cosmosdb-agent-kit and configures it for Cursor.

  3

  Select Cursor when prompted

  The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:

  ◆ Which agents do you want to install to?

  │

  │ ── Universal (.agents/skills) ── always included ────

  │ • Amp

  │ • Antigravity

  │ • Cline

  │ • Codex

  │ ●Cursor(selected)

  │ • Cursor

  │ • Windsurf

  4

  Verify installation

  Confirm successful installation by checking the skill directory location:

  .cursor/skills/cosmosdb-best-practices

  Reload or restart Cursor to activate cosmosdb-best-practices. Access the skill through slash commands (e.g., /cosmosdb-best-practices) or your agent's skill management interface.

  ⚠

  Security & Verification Notice

  We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

  Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.

  Additional Resources

  ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?