Azure Cosmos DB: Partition Keys, RUs, and the Five ConsistenciesOfficial sources4 of 4 sources come from the companies and standards bodies that own the technology.This rates where the sources come from. It doesn't prove every claim.
Cosmos DB SQL API, 5 consistency levels, partition-key design (10GB cap, hot-partition avoidance), RU/s autoscale vs serverless, CosmosClient v3 Direct mode + DefaultAzureCredential, point reads (1 RU), change feed, hierarchical partition keys, vector search GA.
By Amit UpadhyayPublished Updated 15 minArticle 8 of 13 in Databases
AI assistant · answers from this article
1 of 6
A small container
Nothing to add yet
While everything fits in one physical partition, almost any design works. It is the cheapest time to get the partition key right.
On this page
Cosmos DB, in one sentence
Azure Cosmos DB spreads your data across partitions for you, and the partition key you choose decides both how fast it is and what it costs.
You reach for it when a globally distributed app needs predictable low-latency reads and writes at scale on Azure. Not before: it costs access patterns to design up front, and cross-partition queries that stay expensive for the cases the key does not serve.
The cheat sheet
What to use when
You do not need all of this on day one. Each row is one signal and the piece that answers it. Stop at the row your system has reached, or pick one to see it in the picture above.
Where you areThe signalWhat to useWhat it costs
None. One physical partition, modest traffic and a small bill.Nothing extra. A sensible key and the default consistencyNothing
The key is the id, so every query that is not by id fans out, and the request-unit bill shows it.A high-cardinality partition key that matches the main access patternStep 2 ↓A key you effectively cannot change later
A read that knows both the id and the key still runs as a query, at many times the cost.Point reads: the id plus the partition keyStep 3 ↓Data shaped so that the hot read is by key
A dashboard has to see all tenants, and its fan-out query costs hundreds of request units.Build it from the change feed, not from a fan-out queryStep 5 ↓A processor to run, and a view that lags a little
One large tenant’s partition is throttled while the others sit idle.A hierarchical partition keyDesigning for access ↓More of the key needed in each query
Reads cost twice the request units, and a second write region is not possible.Session consistency, unless you can justify moreCommon mistakes ↓Other sessions may see a write slightly later
Start With the Queries, Not the Container
While a container is small and sits in one physical partition, almost any design works and the bill stays low. That's the time to get the partition key right, because it's the one decision you can't change later without copying the container. List your main queries first, then choose the key.
Most Cosmos DB problems arrive as a 429 error or a surprising invoice, and most of them trace back to one early decision: the partition key. Pick one that concentrates traffic and you get throttling no matter how many Request Units you buy. Pick one your queries do not use and every read fans out across every partition.
Cosmos DB hides replication, consensus and global distribution behind Request Units per second, and it is very good at that. What it cannot hide is how your data is split. Below are the concepts that decide cost and speed (partition keys, point reads, consistency levels) and the newer features, such as vector search in the NoSQL API, that are worth knowing about.
Signs your Cosmos DB design needs another look
You picked id as your partition key and now every query not by id fans out
You don't know the difference between Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual
You're scared to read your RU bill
You're using SQL API but issuing cross-partition queries on every request
Pro deep dive15 min full read
Keep reading with Pro
This is one of our advanced production deep dives. Pro unlocks the rest of it, every other deep dive, and the See, Animate, Test and Build modes on every topic.
What it covers
Cosmos DB SQL API, 5 consistency levels, partition-key design (10GB cap, hot-partition avoidance), RU/s autoscale vs serverless, CosmosClient v3 Direct mode + DefaultAzureCredential, point reads (1 RU), change feed, hierarchical partition keys, vector search GA.