Azure Cosmos DB Best Practices

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-diagnostics - Log diagnostics for troubleshooting

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

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

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