Request Units in Azure Cosmos DB

What are Request Units (RUs)?

Azure Cosmos DB is a globally distributed, multi-model database service. To abstract the complexities of various database operations and hardware, it uses a normalized unit of measure called a Request Unit (RU). A Request Unit represents the normalized throughput required to perform various database operations.

Every operation performed on your Azure Cosmos DB database consumes a certain number of RUs. This includes reading an item, writing an item, executing a query, or performing a stored procedure. The number of RUs consumed depends on factors like:

The size of the item being read or written.
The complexity of the operation (e.g., a simple point read vs. a complex query with filters and sorts).
The consistency level chosen for the operation.

How RUs Work

When you provision throughput for your Azure Cosmos DB container or database, you specify the number of RUs per second (RU/s) you want to allocate. This provisioned throughput acts as a ceiling for the number of RUs your operations can consume within any given second.

For example, if you provision 1000 RU/s for a container:

You can perform operations that consume a total of 1000 RUs within one second.
If your operations consume 800 RUs in one second, you have 200 RUs remaining for that second.
If your operations attempt to consume 1200 RUs in one second, the excess 200 RUs will be throttled, and you'll receive a 429 Too Many Requests error.

Azure Cosmos DB automatically scales your provisioned throughput if you're using autoscale or manual scaling settings.

Estimating RU Consumption

Understanding RU consumption is crucial for managing costs and performance. Azure Cosmos DB provides tools and documentation to help estimate RU costs:

Request Units documentation: Microsoft Learn provides detailed breakdowns of RU costs for various operations.
Azure Cosmos DB Emulator: Allows you to test your application and estimate RU consumption locally before deploying to the cloud.
Diagnostic Logs and Metrics: Monitor your actual RU consumption in the Azure portal to identify patterns and optimize.

Example RU Consumption

Here's a simplified example of RU costs for common operations on a 1KB item:

-- Operation Type      | RU Cost (approx.)
            -----------------------|-------------------
            Point Read (Item)      | 1 RU
            Point Write (Item)     | 1 RU
            Query (no filter/sort) | 1 RU per item returned
            Query (with filter/sort)| Varies based on complexity

Key Takeaway: Request Units abstract database operations into a normalized measure, allowing for consistent performance management and cost control across different APIs and hardware.

Optimizing RU Consumption

To optimize your RU consumption and reduce costs, consider these strategies:

Efficient Queries: Design your queries to be as specific as possible, minimizing the data scanned. Use projection to select only the fields you need.
Indexing: Ensure your indexing policy is optimized. Include only the paths you query frequently.
Batching: For multiple writes, consider using stored procedures or batch APIs to group operations and potentially reduce overhead.
Partitioning Strategy: A good partitioning strategy distributes requests evenly across partitions, preventing hot partitions and optimizing throughput.
Consistency Levels: Choose the lowest acceptable consistency level for your application. Lower consistency levels generally consume fewer RUs.

Autoscale vs. Manual Throughput

Azure Cosmos DB offers two primary models for managing throughput:

Manual Throughput: You set a fixed RU/s value. This is suitable for predictable workloads.
Autoscale Throughput: You define a maximum RU/s, and Cosmos DB automatically scales the provisioned throughput up and down within a defined range based on actual usage. This is ideal for variable workloads and can be more cost-effective.