cosmosdb-data-and-queries

Azure Cosmos DB Data Modeling & Queries

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