Cosmos DB: the five consistency levels explained simply
Strong, bounded staleness, session, consistent prefix and eventual, with a comparison table, practical advice and global distribution basics.
On SQL Server, consistency is effectively "strong": after a COMMIT everyone sees the data (readable secondary replicas aside). Cosmos DB offers five consistency levels between two extremes, because data is replicated, including across regions. Here is how I remember them, without jargon.
The five levels, strongest to weakest
| Level | What I understand | Example |
|---|---|---|
| Strong | You always read the latest committed write (linearizability) | Bank balance |
| Bounded staleness | You may read stale data, but bounded: at most K versions or T seconds behind | Near-real-time dashboard across regions |
| Session | Within my session I read my own writes (read-your-writes) | A user editing their profile |
| Consistent prefix | Reads are never out of order; you may be behind | Ordered event feed |
| Eventual | No ordering guarantee, it converges "someday" | Like counters |
A few details from the docs:
- Session is the most widely used level, in single-region and multi-region setups. It relies on a session token returned after every write and kept by the client. If the client is recreated, its token cache is lost and its reads behave like eventual until new writes happen.
- Bounded staleness: the lag is bounded between regions (not within a region). Minimum K and T values are 10 writes or 5 seconds for a single region, and 100,000 writes or 300 seconds for multi-region accounts.
- Consistent prefix: writes grouped in a transaction are visible together.
- The level is set at account level (applied to all databases and containers) and can be relaxed for a specific request on the SDK side. Restart the application after changing the default level.
Practical comparison
| Level | Read quorum | RU cost of reads | Possible data loss in a regional outage (RPO), several regions, one write region |
|---|---|---|---|
| Strong | Local minority (2 replicas) | x2 | 0 |
| Bounded staleness | Local minority (2 replicas) | x2 | K and T |
| Session | Single replica | x1 | under 15 min |
| Consistent prefix | Single replica | x1 | under 15 min |
| Eventual | Single replica | x1 | under 15 min |
For the same amount of RUs, read throughput with strong and bounded staleness is half that of the other levels. Read and write latency is guaranteed under 10 ms at the 99th percentile for all levels, except strong on a multi-region account where write latency depends on network round trips between the farthest regions.
Practical advice
- Default: Session. It covers most user-centric applications.
- Strong only if the business truly requires it, accepting the write latency impact. It is blocked by default for accounts whose regions are more than 8,000 km (5,000 miles) apart, and it can't be combined with multi-region writes.
- Bounded staleness suits global single-write-region apps that want "nearly strong". For multi-region writes the docs call it an anti-pattern.
- On a multi-region account, the Probabilistically Bounded Staleness metric in the portal shows how often you get stronger consistency than the level you configured.
- An application that always reads and writes in the same region is less sensitive to the level.
Global distribution and multi-region writes in brief
flowchart LR
A["Application (region A)"] --> B["Write region A"]
B -->|"asynchronous replication"| C["Read region B"]
B -->|"asynchronous replication"| D["Read region C"]
E["Application (region B)"] --> C
- You add or remove regions at any time; data is replicated automatically. Changing the region list is done separately from any other account change.
- By default only one region accepts writes; the others are read-only. Automatic failover (
--enable-automatic-failover) picks a new write region according to the failover priorities. - Multi-region writes can be enabled on an existing account without downtime:
az cosmosdb update --ids <id> --enable-multiple-write-locations true. It introduces conflict resolution, with a policy configurable per container (for example "last writer wins" on a given path). - Provisioned RUs are available in every region, so cost follows the number of regions.
Lessons learned
- Pick the level based on what a stale read costs the business, not on principle.
- Test session behavior if several application instances must share a token.
- Document the chosen level together with the estimated RPO for a regional outage.