cosmosdb-query-optimization

Azure Cosmos DB Query Optimization

Best practices for writing efficient queries against Azure Cosmos DB.

When to Apply

Reference these guidelines when:

• Writing or optimizing Cosmos DB queries
• Implementing pagination
• Choosing between point reads and queries
• Reducing RU consumption on read operations
• Handling aggregations and sorting

Rules

• query-point-reads - Use point reads when id and partition key are known
• query-aggregate-single-pass - Compute min/max/avg with one scoped aggregate query
• 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
• query-top-literal - Use literal integers for TOP
• query-latest-by-timestamp - Query latest documents with ORDER BY and TOP 1
• query-olap-detection - Detect and redirect analytical queries
• query-distinct-keyword - Use DISTINCT keyword correctly

Full Compiled Document

For all rules expanded: AGENTS.md