Consistency Levels

There’s a famous result in distributed systems called the CAP theorem — when the network partitions (and it always eventually does), you must choose between consistency and availability. You can’t have both at full strength. Cosmos exposes this trade-off as five named, well-defined points on a continuum, and lets you pick which one you want — globally and per-request.

The five levels at a glance

From strongest (slowest, most expensive) to weakest (fastest, cheapest):

Strong

Every read sees the most recent committed write, globally. Linearizable. Disables multi-region writes — you can only have one write region. Use for — bank balances, inventory at last-item, anything where stale = money lost.

Bounded staleness

Reads can lag by at most K operations or T time (e.g. 100,000 versions or 5 seconds, whichever first). Within those bounds, you get a clear “how stale” guarantee. Use for — leaderboards, fraud signals, “fresh enough” dashboards.

Session (default)

Within a single client session, you have read-your-writes consistency, monotonic reads, and consistent prefix. Across sessions, eventual. Use for — virtually every CRUD app, every social feed, every CMS, every cart. The pragmatic default.

Consistent prefix

You may see stale data, but you’ll never see writes out of order. If A happened before B, you’ll never see B without A. Use for — comment threads, event logs, anything where order matters more than freshness.

Eventual

All replicas converge eventually. No ordering, no monotonicity, no read-your-writes. Cheapest. Use for — view counts, like counters, recently-viewed lists.

The session token, demystified

When you use session consistency (the default), the SDK silently maintains a session token per CosmosClient instance. It looks like this — 0:-1#42 — and represents “I’ve seen up to logical sequence 42 on this partition.”

Every write returns a token. Every read sends the latest token along — the read is served from a replica that’s caught up to at least that point. The replica responds with its own current token, and the SDK keeps the highest one for next time.

What this gives you — a single user clicking “save” and then “view” always sees their save. Different users (different sessions) may see things in different orders briefly. That’s the session boundary.

If you need to share session state across processes (e.g. the API server writes, the worker reads), you can serialize and pass the token explicitly via CosmosClient.RequestOptions.

RU cost by level

Reads scale with consistency strength. Approximate cost of a single point read:

Writes are the same cost across levels — Cosmos still has to commit them everywhere either way.

The multi-region constraint

This is the most surprising rule — strong consistency forbids multi-region writes. The reason is mechanical — to guarantee linearizability across regions, every write would need a round-trip to every region, killing throughput. Cosmos refuses to let you opt into that combination.

If you want both global writes and a strict guarantee, the right choice is bounded staleness — strict by some bound, but the bound is per-region.

Picking yours

Don’t pick by gut. Ask the product question — what’s the cost of a stale read?

• “We refund the user, that’s it” → session or weaker.
• “We oversell the last item and disappoint a customer” → bounded staleness.
• “We double-charge or under-charge a financial transaction” → strong.

Most teams pick session at the account level and override to strong on the 2-3 endpoints that genuinely need it.