Best practices for Azure Cosmos DB data design and querying: document modeling, partition key selection, indexing policy, query optimization, and data-access patterns.
When to Apply
Reference these guidelines when designing documents, choosing partition keys, defining indexing policy, or writing and optimizing queries against Azure Cosmos DB.
Rules
Data Modeling
- model-avoid-2mb-limit - Keep Items Well Under 2MB Limit
- model-denormalize-reads - Denormalize for Read-Heavy Workloads
- model-embed-related - Embed Related Data Retrieved Together
- model-id-constraints - Follow ID Value Length and Character Constraints
- model-json-serialization - Handle JSON serialization correctly for Cosmos DB documents
- model-nesting-depth - Stay Within 128-Level Nesting Depth Limit
- model-numeric-precision - Understand IEEE 754 Numeric Precision Limits
- model-reference-large - Reference Data When Items Grow Large
- model-relationship-references - Use ID references with transient hydration for document relationships
- model-schema-versioning - Version Your Document Schemas
- model-type-discriminator - Use Type Discriminators for Polymorphic Data
Partition Key Design
- partition-20gb-limit - Plan for 20GB Logical Partition Limit
- partition-avoid-hotspots - Distribute Writes to Avoid Hot Partitions
- partition-hierarchical - Use Hierarchical Partition Keys for Flexibility
- partition-high-cardinality - Choose High-Cardinality Partition Keys
- partition-immutable-key - Choose Immutable Properties as Partition Keys
- partition-key-length - Respect Partition Key Value Length Limits
- partition-query-patterns - Align Partition Key with Query Patterns
- partition-synthetic-keys - Create Synthetic Partition Keys When Needed
Indexing Strategies
- index-composite-direction - Composite Index Directions Must Match ORDER BY
- index-composite - Use Composite Indexes for ORDER BY
- index-exclude-unused - Exclude Unused Index Paths
- index-lazy-consistent - Understand Indexing Modes
- index-path-syntax - Use Correct Indexing Path Syntax
- index-range-vs-hash - Choose Appropriate Index Types
- index-spatial - Add Spatial Indexes for Geo Queries
Query Optimization
- query-aggregate-single-pass - Compute min/max/avg with one scoped aggregate query
- query-avoid-cross-partition - Minimize Cross-Partition Queries
- query-avoid-scans - Avoid Full Container Scans
- query-distinct-keyword - Use DISTINCT keyword to eliminate duplicate results efficiently
- query-latest-by-timestamp - Query "latest" documents with explicit ORDER BY and TOP 1
- query-olap-detection - Detect and Redirect Analytical Queries Away from Transactional Containers
- query-order-filters - Order Filters by Selectivity
- query-pagination - Use Continuation Tokens for Pagination
- query-parameterize - Use Parameterized Queries
- query-point-reads - Use Point Reads Instead of Queries for Known ID and Partition Key
- query-top-literal - Parameterize TOP Values Safely
- query-use-projections - Project Only Needed Fields
Design Patterns
- pattern-change-feed-materialized-views - Use Change Feed for cross-partition query optimization with materialized views
- pattern-efficient-ranking - Use count-based or cached rank approaches instead of full partition scans for ranking
- pattern-service-layer-relationships - Use a service layer to hydrate document references before rendering