Azure Cosmos DB Best Practices

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 60+ rules across 9 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
• 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
• 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
• 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-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
• 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

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-java-content-response - Enable content response on write operations (Java)
• sdk-java-spring-boot-versions - Match Java version to Spring Boot requirements
• sdk-local-dev-config - Configure local development to avoid cloud conflicts
• 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-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

How to Use

Read individual rule files for detailed explanations and code examples:

rules/model-embed-related.md
rules/partition-high-cardinality.md
rules/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md