Troubleshooting Azure Cosmos DB NoSQL Query Timeout

Troubleshooting

Problem

This article provides steps to diagnose and resolve query timeout issues in Azure Cosmos DB using the NoSQL API.

Symptom

Queries fail with Request Timeout or Gateway Timeout errors.
Query execution exceeds the configured Request Timeout (default: 60 seconds).
High latency or incomplete results returned.

Cause

Complex Queries
- Large JOINs, CROSS JOINs, or multiple filters.
- Heavy aggregation or ORDER BY without proper indexing.
Insufficient RU/s (Request Units per second)
- Query requires more RU/s than provisioned.
- Throttling occurs due to RU limits.
Large Data Scans
- Missing or inefficient indexes.
- Queries scanning entire container.
Network Latency
- Client application far from Cosmos DB region.
- Poor connectivity or transient network issues.

Environment

Azure Cosmos DB NoSQL

Diagnosing The Problem

Step 1: Check Query Metrics

Enable Query Metrics in SDK or Azure Portal.
Look for:
- Retrieved Document Count
- Index Hit Ratio
- Request Charge (RU)

Step 2: Optimize Query

Use SELECT specific fields instead of SELECT *.
Avoid unnecessary JOINs.
Use TOP and pagination for large result sets.

Step 3: Validate Indexing Policy

Ensure required properties are indexed.
For ORDER BY, confirm composite indexes exist.

Step 4: Increase RU/s or Use Autoscale

If RU consumption is high, increase throughput or enable Autoscale.

Step 5: Use Continuation Tokens

For large datasets, implement continuation tokens for paginated queries.

Step 6: Check SDK Timeout Settings

Default SDK timeout may be too low; increase if needed.

Step 7: Monitor Region & Connectivity

Ensure client and Cosmos DB are in the same region.
Use Azure Network Watcher for latency checks.

Resolving The Problem

Resolution will vary based on the outcome of your diagnostic steps above.

Additional Tools

Azure Monitor: Track query performance and RU consumption.
Cosmos DB Diagnostics: Identify slow queries and indexing issues.

References

Azure Cosmos DB Query Performance Tips
Indexing in Azure Cosmos DB

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB66","label":"Technology Lifecycle Services"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SSTKH9","label":"Microsoft Azure"},"ARM Category":[{"code":"a8mKe000000004XIAQ","label":"AZURE"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":""}]

Tips

Troubleshooting Azure Cosmos DB NoSQL Query Timeout