Skip to content

Commit 7431cd6

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #4875 from richagaur/richagaur/understanding-ru-consumption
understanding ru consumption in cosmos db
2 parents f51ec23 + f215412 commit 7431cd6

2 files changed

Lines changed: 201 additions & 0 deletions

File tree

‎articles/cosmos-db/TOC.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,8 @@
315315
href: throughput-serverless.md?context=/azure/cosmos-db/context/context
316316
- name: Best practices for scaling provisioned throughput
317317
href: scaling-provisioned-throughput-best-practices.md?context=/azure/cosmos-db/context/context
318+
- name: Understanding request unit consumption
319+
href: understand-request-unit-consumption.md?context=/azure/cosmos-db/context/context
318320
- name: Burst capacity
319321
items:
320322
- name: Burst capacity overview

‎articles/cosmos-db/understand-request-unit-consumption.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: Understanding Request Units Consumption
3+
description: This article explains how request units are consumed in Azure Cosmos DB with some examples.
4+
author: richagaur
5+
ms.author: richagaur
6+
ms.service: azure-cosmos-db
7+
ms.topic: concept-article
8+
ms.date: 04/21/2026
9+
appliesto:
10+
- ✅ NoSQL
11+
- ✅ MongoDB
12+
- ✅ Apache Cassandra
13+
- ✅ Apache Gremlin
14+
- ✅ Table
15+
show_latex: true
16+
---
17+
18+
# Understand request units consumption in Azure Cosmos DB
19+
20+
Azure Cosmos DB uses request units (RUs) as a normalized measure of the resources required to execute database operations. Instead of managing provisioning of resources such as CPU, memory, and I/O independently, RUs provide a simple and consistent way to understand how different operations consume resources. Each operation consumes Request Units reflecting the work performed by the service to execute the request with a focus on trying to ensure predictability.
21+
This article explains what influences RU consumption, how common operations consume RUs, and practical ways to design efficient workloads.
22+
23+
## What influences RU consumption
24+
25+
### Document size
26+
Request units consumption for an operation scales with document size due to the increased CPU and I/O needed to process larger documents.
27+
28+
|**Document Size** |**Read Operation** |**Write Operation**
29+
|---------|---------|---------|
30+
|1 KB |1.00 | 4.95 |
31+
|2 KB |1.04 | 6.29 |
32+
|4 KB |1.14 | 6.67 |
33+
|8 KB |1.33 | 7.04 |
34+
|16 KB |1.67 | 9.52 |
35+
|32 KB |2.19 | 11.23 |
36+
|64 KB |4.76 | 22.67 |
37+
|128 KB |9.95 | 48.19 |
38+
|256 KB |20.28 | 98.29 |
39+
|512 KB |40.95 | 184.57 |
40+
|1,024 KB |145.90 | 625.00 |
41+
|2,048 KB |291.80 | 1250.00 |
42+
43+
> [!NOTE]
44+
> Read RUs mentioned are applicable to session and eventual consistency.
45+
46+
### Indexing
47+
Indexes improve query performance but increase the RUs consumed by write operations. Indexing only required properties reduces RU consumption for writes and updates while balancing query performance. For more information on how to index only required properties, see [indexing policy](index-policy.md).
48+
49+
### Configuration choices
50+
Some features require more processing that influences RU consumption, such as:
51+
52+
* Consistency level of read requests
53+
* Computed properties
54+
* Customer managed keys
55+
* Dynamic data masking
56+
57+
### RU consumption in multi-region accounts
58+
When an account has multiple regions, Azure Cosmos DB provisions throughput independently in each region, enabling low latency access and high availability.
59+
60+
* **Write** operations consume RUs for writing data in the primary region and for replicating the data to additional regions. As a result, write RU consumption increases with the number of regions configured.
61+
* **Read** operations consume RUs in the region they're served from.
62+
63+
This model ensures predictable performance and durability while making global distribution transparent.
64+
65+
### RU consumption in multi-region write accounts
66+
67+
Multi-region write accounts allow write operations across all account regions. RU consumption for document operations follows the same general principles as multi-region accounts, with more processing to coordinate conflicting writes across regions.
68+
Because of this added coordination, the unit price of RUs in this configuration differs from single-region write setups. For current pricing details, see [Azure Cosmos DB pricing](https://azure.microsoft.com/pricing/details/cosmos-db/).
69+
70+
## How request units consumption evolves
71+
72+
Request units consumption in Azure Cosmos DB evolves over time as platform efficiency improves through hardware upgrades and service optimizations. These improvements are typically passed on to customers automatically, often resulting in more efficient RU consumption without any application changes. For example, binary encoding of stored data reduced the persisted size of documents, which lowered RU consumption for read operations without requiring any application changes.
73+
74+
Although specific RU values can change over time, the principles remain consistent and predictable. Customers can achieve better cost efficiency by focusing on the factors that influence RU consumption, including document size, indexing decisions, configuration choices, and access patterns.
75+
76+
## Document operations and request units
77+
78+
Request units are consumed based on the work required to perform an operation. This section explains how RUs are consumed across common document operations, using illustrative examples to highlight the underlying principles.
79+
80+
81+
> [!IMPORTANT]
82+
> The RU values described in this document are illustrative and reflect how Azure Cosmos DB processes operations at a given point in time.
83+
84+
### Write Operations
85+
Different types of write operations follow similar principles. RU consumption primarily depends on **document size** and **indexed properties**.
86+
87+
#### Create
88+
A create operation includes:
89+
* Inserting the document
90+
* Adding indexed terms defined by the indexing policy
91+
92+
For example, RUs consumed for a 1-KB document with ten indexed terms in one region:
93+
5.0 (document size based) + 0.2 × 10 (indexing) = 7 RUs
94+
95+
#### Updates (replace)
96+
Update operations involve:
97+
* Deleting the existing document
98+
* Inserting the new document
99+
* Deleting any modified indexed terms
100+
* Inserting any modified indexed terms
101+
102+
For example, updating a 1-KB document with two modified indexed terms:
103+
5.0 (deletion) + 5.0 (insertion) + 0.2 × 2 (index deletion) + 0.2 × 2 (index insertion) = 10.8 RUs
104+
105+
> [!Tip]
106+
> Updates approximately consume twice as many RUs as creates when only a small number of index terms change.
107+
108+
#### Patch
109+
110+
Patch operations update specific properties within a document. The RUs consumed is similar to a replace operation and scales with the number of modified properties.
111+
112+
For example, updating a 1-KB document with two modified indexed terms using patch operation:
113+
5.0 (deletion) + 5.0 (insertion) + 0.2 × 2 (index removal) + 0.2 × 2 (index insertion) + 0.4 * 2 (base for patch) = 11.6 RUs
114+
115+
#### Delete
116+
117+
Delete operations includes:
118+
* Deleting the document
119+
* Deleting indexed terms
120+
121+
For example, deleting a 1-KB document with ten indexed terms:
122+
5.0 (document size) + 0.2 × 10 (index removal) = 7.0 RUs
123+
124+
#### Stored procedures
125+
Stored procedures execute server-side logic and can perform multiple operations within a single request. Their RU consumption depends on the complexity and scope of the logic executed.
126+
To reduce the variability in RUs consumed due to the nature of stored procedures, alternatives such as transactional batch operations or bulk APIs are recommended where feasible.
127+
128+
### Read Operations
129+
130+
#### Point Reads
131+
Point reads (using document ID and partition key) are read operations that are most efficient in resource consumption. RU consumption is based on the persisted document size.
132+
133+
|**Document Size** |**RUs for point read** |
134+
|---------|---------|
135+
|1 KB |1.00 |
136+
|100 KB |~10.00 |
137+
138+
#### Feed operations
139+
Feed operations include Change Feed and Read Feed. These operations return a stream or batch of documents rather than a single document.
140+
Feed operations consume RUs based on:
141+
* The number of documents processed
142+
* The size of those documents
143+
144+
For example, processing five 1-KB documents through a feed consumes approximately the same RUs as reading those five documents individually.
145+
146+
This design provides predictable, linear scaling: as the volume of data processed increases, RU consumption increases proportionally. RU usage depends on data changes and volume, not on how quickly a client consumes the feed.
147+
148+
### Query Operations
149+
Query operations vary the most in RU consumption because they depend on the query shape and how effectively indexes are used. Azure Cosmos DB tries to ensure that the same query, when executed on the same data, consumes the same number of RUs across repeated executions.
150+
151+
Factors affecting Query RUs are:
152+
* Size of the source data
153+
* Size of the result set
154+
* Page size and page count
155+
* Document loading
156+
* Document parsing
157+
* Index lookup
158+
* Scan
159+
* Number and nature of predicates
160+
* Use of user-defined functions
161+
* Projections
162+
163+
### Background operations
164+
Azure Cosmos DB performs certain background operations on behalf of users. These tasks run opportunistically when throughput is available and can consume a proportion of the provisioned throughput.
165+
166+
Examples include:
167+
* Delete by partition key
168+
* Time-to-live (TTL) deletion
169+
* Unique key reindexing
170+
* Global Secondary Index (GSI) maintenance
171+
172+
## Measuring and monitoring RU consumption
173+
174+
Each request to Azure Cosmos DB returns the number of request units (RUs) consumed as part of the response. This value is exposed through the RequestCharge property and represents the RUs consumed by that specific operation.
175+
176+
For query workloads, RU consumption and performance depend on the query shape and index utilization. Enabling [query metrics](optimize-cost-reads-writes.md#metrics-for-troubleshooting-queries) allows you to see how RU consumption is distributed across query execution phases, helping identify opportunities to optimize query performance and reduce RU consumption.
177+
178+
To understand RU consumption at a broader level, you can monitor **Total Request Units** metrics in the Azure portal. This metric shows RU consumption at the container or database level and supports filters like database name, container name, operation type, region, and response status.
179+
180+
![Screenshot of Total Request Units metric in monitoring tab of Azure Cosmos DB account.](media/monitor-request-unit-usage/request-unit-usage-metric.png)
181+
182+
## Key takeaways and best practices
183+
184+
### Keep document size efficient
185+
* RU consumption increases with document size. Smaller documents generally require fewer resources to read, write, and index.
186+
* For large entities, consider modeling data across multiple documents instead of storing everything in a single document.
187+
* Avoid storing large binary payloads in documents. A common best practice is to store this data in Azure Blob Storage and keep only a reference in Azure Cosmos DB.
188+
### Index intentionally
189+
* Indexing speeds up queries but raises RU consumption for writes and updates. Tailor your indexing policy to target only the properties needed for filtering or sorting.
190+
* Design queries to use relevant indexes such as range, composite, or filtered to minimize unnecessary scans.
191+
### Choose efficient access patterns
192+
* Point reads (using document ID and partition key) are the most efficient way to read data.
193+
* Queries scale predictably with the amount of data processed, so shaping queries to return only the required data can significantly reduce RU usage.
194+
### Design for partitioning and locality
195+
* Choose a partition key that evenly distributes data and aligns with common access patterns.
196+
* Where appropriate, colocate related entity types within the same container to reduce cross-container operations and network overhead.
197+
### Monitor RU usage and iterate
198+
* Use request-level diagnostics and Azure Monitor metrics to understand where RUs are being consumed.
199+
* Focus first on identifying operations consuming high RUs, then refine data modeling, indexing, or queries as needed.

0 commit comments

Comments
 (0)