Azure Cosmos DB Best Practices

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 45+ rules across 8 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-denormalize-reads - Denormalize for read-heavy workloads
• •model-schema-versioning - Version your document schemas
• •model-type-discriminator - Use type discriminators for polymorphic data

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-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

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

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