Cosmos DB Request Units (RU/s)

Request Units (RUs) are a normalized measure of the computational resources required to perform a database operation on Azure Cosmos DB. Resources include CPU, memory, IOPS, and throughput. Every operation—whether a point read, a query, a write, or a stored procedure execution—consumes a certain number of RUs. You provision throughput in terms of RUs per second (RU/s). Cosmos DB guarantees that the provisioned RU/s will be available for your operations, subject to consistency models and partitioning.

Cosmos DB is a globally distributed, multi-model database. To provide predictable performance and SLAs (99.99% availability for single-region writes, 99.999% for multi-region writes), it needs a unified way to measure and allocate resources across different APIs (SQL, MongoDB, Cassandra, Gremlin, Table) and consistency levels. RU/s abstracts away the underlying hardware and allows you to think purely in terms of throughput. It also enables a consumption-based pricing model where you pay only for what you provision or consume.

Each operation's RU cost depends on: - Operation type: Writes cost more than reads. A 1 KB point read (single item by ID and partition key) costs 1 RU. The same write costs 5 RUs. - Item size: Larger items consume more RUs. For point reads, RU cost scales linearly with item size (e.g., a 2 KB item costs ~2 RUs). - Query complexity: Indexed queries that scan fewer partitions cost fewer RUs. Aggregations, joins, and ORDER BY increase RU cost. - Consistency level: Stronger consistency (Strong, Bounded staleness) costs more RUs than weaker (Eventual, Consistent prefix, Session). Session consistency is the default and adds a small overhead. - Indexing policy: Queries that can use the index cost fewer RUs than full scans. Customizing indexing (e.g., excluding unused paths) reduces RU consumption.

You can configure throughput in two modes: - Provisioned throughput: You set a specific number of RU/s (e.g., 400 RU/s). Cosmos DB reserves that capacity. You pay per hour for the provisioned RU/s, regardless of actual usage. This mode supports autoscale (auto-scaling from 10% to 100% of max RU/s) and manual scaling. Suitable for predictable workloads. - Serverless: You pay only for the RUs consumed by your operations, measured per hour. There is no provisioning. However, serverless has a maximum throughput limit (currently 5,000 RU/s per container) and is not available for all APIs or consistency levels. Suitable for intermittent or low-traffic workloads.

If you exceed your provisioned RU/s in a given second, Cosmos DB returns HTTP 429 (Too Many Requests) with a x-ms-retry-after-ms header indicating how long to wait. The SDKs automatically retry up to 9 times by default, with exponential backoff. You can configure RetryOptions on the CosmosClient. Rate-limiting can occur if:

RU/s is allocated evenly across physical partitions. Each physical partition gets a share of the total RU/s. For example, with 10,000 RU/s and 4 physical partitions, each partition gets 2,500 RU/s. If one partition receives more requests than its share, requests may be rate-limited even if total RU/s is not exceeded. This is why choosing a good partition key is critical: it distributes both data and throughput evenly.

RU costs differ by consistency level. For point reads:

Multi-region writes (with Strong consistency) are not supported. For writes, RU cost is the same across all consistency levels because writes are always replicated to a quorum.

You can estimate RU costs using: - Cosmos DB Capacity Planner: A web-based tool to estimate RU/s based on data size, operations, and consistency. - `x-ms-request-charge` header: Every response includes the actual RU cost for that operation. - Metrics in Azure Portal: Monitor RU consumption per partition, total RU/s, and 429 count.

Using Azure CLI:

az cosmosdb sql container throughput update \
  --resource-group myResourceGroup \
  --account-name myAccount \
  --database-name myDatabase \
  --name myContainer \
  --throughput 400

For autoscale:

az cosmosdb sql container throughput update \
  --resource-group myResourceGroup \
  --account-name myAccount \
  --database-name myDatabase \
  --name myContainer \
  --max-throughput 4000

Using PowerShell:

Update-AzCosmosDBSqlContainerThroughput `
  -ResourceGroupName myResourceGroup `
  -AccountName myAccount `
  -DatabaseName myDatabase `
  -Name myContainer `
  -Throughput 400

In Azure Portal, under Metrics, you can create charts for:

Set alerts when normalized RU consumption exceeds 90% or 429 count spikes.

A large online retailer uses Cosmos DB (SQL API) to store product catalog data with 10 million items, each about 2 KB. They experience 20,000 point reads per second during peak hours, with 100 writes per second. Using Session consistency, each read costs ~2 RUs (since items are 2 KB), so reads consume 40,000 RU/s. Writes cost 5 RUs each, adding 500 RU/s. They provision 45,000 RU/s manually. However, during Black Friday, traffic spikes to 30,000 reads/s. They get 429 errors. Solution: Enable autoscale with max RU/s of 90,000. Autoscale automatically increases throughput to 90,000 RU/s during the spike, then scales down to 4,500 RU/s (10%) afterward, saving costs. They also implement client-side retry with exponential backoff. Misconfiguration: Initially they chose a partition key of category, causing hot partitions for popular categories. They changed to productId (high cardinality) to distribute load evenly.

A manufacturing company ingests sensor data from 100,000 devices, each sending a 1 KB document every minute. That's 1,667 writes per second. Each write costs 5 RUs, totaling ~8,333 RU/s. They also run analytical queries on the last hour of data. They use serverless mode because traffic is constant but low (under 5,000 RU/s per container). However, they need to store data for 30 days. With serverless, storage costs are separate. They partition by deviceId and use TTL to auto-delete data older than 30 days. They monitor RU consumption and see it averages 2,000 RU/s, well under the serverless limit. A common mistake: They initially used provisioned throughput at 10,000 RU/s, paying for idle capacity. Switching to serverless reduced costs by 60%.

A social media platform with users worldwide uses Cosmos DB with multi-region writes. They have 100 million users, each reading their timeline (point read of 5 KB) several times a day. They provision 1,000,000 RU/s distributed across three regions. They use Session consistency. They monitor normalized RU consumption per partition and see one partition hitting 100% while others are at 20%. This indicates a hot partition due to a bad partition key (e.g., region). They migrate to a composite partition key (userId + region) to spread load. They also use the Cosmos DB Capacity Planner to estimate RU/s for new features. When misconfigured, 429 errors caused user-facing latency, leading to churn. Proper monitoring and alerting on 429 count and normalized RU consumption prevented issues.