Cosmos DB Consistency Levels Demystified: Strong to Eventual and the Latency-Correctness Trade-off

You wrote a value, then read it back a millisecond later, and got the old value. The code is correct. The SDK is correct. Nothing is broken. You just met eventual consistency, and the database did exactly what you configured it to do — it gave you a fast answer instead of a fresh one. Azure Cosmos DB — Microsoft’s globally-distributed, multi-model NoSQL database — does not make you choose between “consistent” and “fast” as a binary. It hands you a dial with five settings: Strong, Bounded Staleness, Session, Consistent Prefix, Eventual. Each one is a precise, documented contract about how stale a read is allowed to be, and each one buys you something — lower write latency, higher read availability, cheaper reads — in exchange for relaxing how fresh and how ordered your reads are guaranteed to be.

Most teams never turn the dial. They take the account default (Session, usually the right call) and move on — fine until the day a financial balance reads stale, a multi-region failover serves data that “went backwards,” or someone sets the account to Strong for safety and watches cross-region write latency triple and a region outage take writes offline. The consistency level is not a checkbox you tick once — it is a per-workload, sometimes per-request decision about how much correctness you trade for latency, availability and cost. Get it wrong in the safe direction and you overpay and lose availability; get it wrong in the loose direction and you ship a correctness bug that only appears under replication lag — the worst kind to debug.

This article gives you the mental model first — the guarantee each level makes, plainly, with the anomaly it allows — then the comparison grids and decision tables to pick correctly, the architecture walkthrough of how Cosmos enforces these guarantees across regions, and finally the override and troubleshooting mechanics. By the end you read the five levels the way a database engineer does: not “strong = good, eventual = bad,” but five points on a documented trade-off curve — and you know which point each workload belongs on, and how to override it for the rare request that needs something else.

What problem this solves

A database that keeps copies of your data in multiple regions (or multiple replicas in one region) has a physics problem: a write must be acknowledged somewhere before the client is told “done,” and a read must be served from somewhere — and those two somewheres are separated by the speed of light and a replication queue. Insist that every read sees every write the instant it’s acknowledged, no matter which replica answers, and you must coordinate across replicas on every operation — coordination that costs latency and availability. Allow reads to be a little behind and you can serve them from the nearest replica instantly — fast and highly available, but sometimes stale. Consistency level is the name of that trade-off, made explicit and selectable.

Without understanding it, three failure modes recur. The silent correctness bug: a developer assumes read-your-own-writes but the workload runs at Eventual, so under replication lag the read returns stale data — a cart that “forgets” an item, a profile update that “didn’t save,” a balance wrong for a few seconds. It passes every test, because tests run against a single replica with no lag. The over-tightening tax: someone sets the account to Strong “to be safe,” and now every cross-region read pays a coordination cost, write latency climbs, read RU charges roughly double versus Eventual, and — the surprise — the account can no longer accept writes during a regional partition, because Strong cannot keep its contract without a quorum. The failover surprise: a loosely-configured account serves data that appears to “go backwards” after a region failover, because reads jumped to a replica that was behind, violating an ordering assumption the app baked in.

Who hits this: anyone running Cosmos DB at more than trivial scale, especially multi-region and multi-region-write (active-active) topologies where the trade-offs are sharpest. It bites e-commerce (cart and inventory correctness), fintech (balances, ledgers), gaming (leaderboards, sessions), and IoT/telemetry (high-write, staleness-tolerant) — each landing on a different point of the dial. The fix is never “just use Strong” or “just use Eventual”; it’s knowing the contract and cost of each level and matching it to each container’s read pattern.

Here is the entire field in one frame — the five levels, the one-line guarantee, and the headline cost — before we go deep:

Learning objectives

By the end of this article you can:

• State the exact guarantee each of the five consistency levels makes — and, just as importantly, the anomaly each one allows — without hand-waving “strong vs eventual.”
• Reason about the latency, throughput (Request Unit), availability and cost consequences of each level, and explain why Strong costs more and Eventual costs less in concrete terms.
• Pick the right default consistency level for an account and justify it against the workload’s read pattern.
• Override consistency per request to relax or (within limits) tighten the guarantee for a specific operation, and know which directions are legal.
• Configure the level and the Bounded Staleness window (max staleness prefix K and max staleness interval T) with az CLI and Bicep, and read the real minimum/maximum bounds.
• Explain how Session consistency works under the hood with the session token, why it can break across instances, and how to propagate the token correctly.
• Predict how each level behaves during a regional failover and in a multi-region-write topology, including conflict resolution.
• Diagnose the classic production symptoms — stale read-your-own-writes, post-failover “data went backwards,” surprise RU and latency from over-tightening — and apply the precise fix.

Prerequisites & where this fits

You should know the Cosmos DB basics: an account is the top-level resource (with one or more regions associated), inside which live databases and containers (the NoSQL-API equivalent of tables/collections), and that containers are sharded by a partition key into physical partitions. You should understand that throughput is provisioned (or serverless) and metered in Request Units per second (RU/s) — an abstraction over the CPU, memory and IOPS a request consumes — and that a point read of a 1 KB item costs 1 RU as a baseline. Comfort with az in Cloud Shell, reading JSON, and the idea that a globally-distributed database keeps replicas in multiple regions will carry you through.

This sits in the Data / distributed-systems track. It assumes the data-model and API choices are already made — if you’re still deciding which API to point at Cosmos, Choosing a Cosmos DB API: NoSQL vs MongoDB vs Cassandra vs Gremlin vs Table Decoded is upstream of this, and consistency interacts with the API (the MongoDB and Cassandra APIs map their own consistency notions onto these five). It pairs with event-driven patterns: the Cosmos DB Change Feed in Action: Event-Driven Pipelines with Azure Functions and the Processor reads an ordered log whose ordering guarantees are exactly the Consistent Prefix story below. If you’re wiring serverless compute to Cosmos, Wiring Azure Functions to Storage Queues and Cosmos DB: A Hands-On Input/Output Binding Tutorial shows the binding layer that inherits whatever consistency you set here.

A quick map of which layer owns which part of the consistency decision, so you know who to talk to:

Core concepts

Five mental models make every later decision obvious.

Consistency is a contract about staleness, not a quality rating. Each level is a guarantee the database honours plus an anomaly it explicitly permits. “Strong” is not “better quality data” — the bytes are identical at every level once replication completes. The difference is purely when you may observe a write from a replica that isn’t the one that accepted it. Read each level as “what is the worst staleness I can ever see?” — not as a grade.

The dial is a global ordering, not five unrelated modes. The five levels form a strict spectrum from strongest to weakest: Strong → Bounded Staleness → Session → Consistent Prefix → Eventual. A stronger level provides every guarantee a weaker one does, plus more. That ordering is why per-request overrides can only relax, never tighten beyond the account default: a client can ask for weaker than the account promises but cannot conjure a stronger guarantee than the account was provisioned to enforce, because the machinery for the stronger contract may not be running.

Strength costs latency, availability and RUs — concretely. A stronger guarantee means a write must be durably replicated to more replicas before acknowledgement, and a read must be served from a replica known to be caught up. That coordination is the cost. Two numbers to internalise: reads at Strong or Bounded Staleness consume roughly 2× the RUs of the same read at the looser levels (they may consult multiple replicas), and Strong forbids multi-region write entirely and reduces write availability during a partition, because it cannot keep its promise without a quorum it may not have.

Session is the default for a reason: it’s the sweet spot. Most apps need exactly one guarantee — read-your-own-writes within a user’s session — and nothing more. A user updates their profile and expects to see the update; they do not care whether another user across the world sees it 200 ms later. Session delivers precisely this at near-Eventual cost and latency, scoped by a session token the SDK passes on each request. Hence the default, and hence most workloads should leave it there.

Consistency interacts with topology, not just config. The same level behaves differently in a single-region account, a multi-region read account (one write region, several read regions), and a multi-region-write account (active-active). Strong is only meaningful single-region. Multi-region write requires a level no stronger than Session and brings conflict resolution into play, because two regions can accept writes to the same item at once. You cannot reason about consistency without knowing the region topology.

The vocabulary in one table

Before the deep sections, pin down every moving part. The glossary at the end repeats these for lookup; this table is the model side by side:

The five levels, one at a time

This is the heart of the article. For each level: the guarantee, the anomaly it allows, the cost, and when to choose it. Read your workload’s row in the summary, then the detail for the levels you’re choosing between.

First, the canonical comparison — every level against every axis that matters. Keep this table open; everything else explains it:

Strong — linearizable, and the price of it

Guarantee. A read is guaranteed to return the most recent committed version of an item, globally. Once a write is acknowledged, every subsequent read from any client, anywhere, sees that write or a newer one — never an older value. This is linearizability: the system behaves as if there were a single copy of the data and operations happened in a single global order.

Anomaly it allows. None of the staleness anomalies. Strong is the absence of staleness. What it does not protect against is application-level logic bugs — it’s a freshness guarantee, not a transaction-isolation guarantee across items.

The cost, concretely. To promise a globally-latest read, a write must be durably committed to a quorum of replicas before acknowledgement, and reads consult enough replicas to be certain they have the latest — which is why Strong reads cost roughly 2× the RUs of Eventual and write latency is the highest of any level. The structural constraint: Strong is incompatible with multi-region write (two regions cannot both claim “I have the latest” at once), and in a multi-region read account it restricts where writes can be acknowledged. During a regional partition Strong sacrifices write availability rather than break its promise — the CAP-theorem trade made explicit.

When to choose it. Single-region accounts where a stale read is a correctness defect you cannot tolerate even for milliseconds: a financial ledger’s running balance, a distributed lock or leader-election record, an inventory decrement that must never oversell. If your account is multi-region for latency or DR, Strong is usually the wrong choice — you give up the multi-region write and availability benefits you paid for.

Bounded Staleness — Strong with a tunable leash

Guarantee. Reads are guaranteed to lag the latest write by at most K versions (updates) OR at most T time — whichever you configure — and never more. Within that window a read may be slightly behind; beyond it, never. Crucially, Bounded Staleness also preserves global order (a “consistent prefix” plus a bounded gap), so you never see writes out of sequence — just possibly a slightly old sequence.

Anomaly it allows. A read may be stale, but only up to the bound. If you set K = 100 operations and T = 5 seconds, a read can be at most 100 writes or 5 seconds behind the latest, whichever is hit first. Outside that, the system enforces freshness.

The cost, concretely. Like Strong, Bounded Staleness reads consume ~2× RUs and writes cost more than the looser levels, because enforcing the bound requires replica coordination. It is the natural choice when Strong’s “zero staleness” is more than you need but Eventual’s “unbounded staleness” is unacceptable and you can name a tolerable lag. Note the enforced floors: the bounds cannot be set arbitrarily tiny, and the minimums differ for single- vs multi-region accounts.

When to choose it. Near-real-time systems with a known, expressible staleness budget: a trading dashboard up to 5 seconds behind but never more; a leaderboard that can lag 100 updates but not show wildly stale ranks; a monitoring view where “at most 10 seconds old” is a contractual SLA. The test: can you write down a number for “how stale is too stale”? If yes, Bounded Staleness fits.

The two bounds work as an OR: the system enforces whichever is reached first. Set both; the tighter one in practice governs. Lower bounds mean fresher reads but tighter coordination (closer to Strong’s cost and availability profile); higher bounds relax toward Session.

Session — read-your-own-writes, scoped to you

Guarantee. Within a single client session (one logical sequence of operations carrying the same session token), you get the strong-ish guarantees that matter to a user: read-your-own-writes (you always see your own latest write), monotonic reads (you never see time go backwards within the session), monotonic writes, and writes-follow-reads. Across different sessions, no such promise — another user might see your write later.

Anomaly it allows. Cross-session staleness. If session A writes and session B reads, B may get the old value until replication catches up. Within a session, none of the read anomalies occur. This is exactly the guarantee a typical web request needs: the user who made a change sees their change; other users’ freshness is not their concern.

The cost, concretely. Session reads cost 1× RUs and write latency is low — nearly as cheap and fast as Eventual while delivering the per-user correctness almost every app wants. It is fully compatible with multi-region write. The one operational catch: the guarantee rides on the session token, an opaque string the SDK manages automatically within a single client object. Span sessions across processes (write on server A, read on server B, no token sharing) and read-your-own-writes does not automatically hold — you must propagate the token, covered in the Session-token section below.

When to choose it. This is the default and the right answer for the vast majority of workloads: user profiles, shopping carts, social posts, comments, preferences, any data scoped to and read by the same user who wrote it. Leave the account at Session unless a specific container has a stronger or weaker need.

Consistent Prefix — order without freshness

Guarantee. Reads never see writes out of order. If writes happened in the order W1, W2, W3, a read will see some prefix of that sequence — (), (W1), (W1,W2), or (W1,W2,W3) — but never a gap or a reorder like (W1,W3) or (W2) before (W1). It may be behind (you might read only up to W1 while W3 already happened), but what you read is always a valid prefix of the true history.

Anomaly it allows. Staleness (you may be behind the latest), but not reordering. You won’t read your own writes from a different replica, and you have no upper bound on how far behind you might be — but the sequence is always coherent.

The cost, concretely. Reads cost 1× RUs, write latency is low, and it is compatible with multi-region write. It is slightly stronger than Eventual (it adds the ordering guarantee) at the same cost profile, so when ordering is the property you actually need, prefer it over Eventual.

When to choose it. Streams and logs where the order of events is semantically important but the latest-ness is not: an audit trail, an event-sourced aggregate, a feed where seeing items out of order would be wrong but a slight lag is fine. This is also the ordering guarantee that underpins reading the change feed in order. If your reader’s correctness depends on “I must process events in the order they occurred,” Consistent Prefix is the floor.

Eventual — fastest, cheapest, loosest

Guarantee. The only promise is convergence: absent further writes, all replicas will eventually agree on the same value. There is no ordering guarantee and no freshness guarantee in the meantime — reads can be stale, can go backwards, can see writes out of order across replicas.

Anomaly it allows. All of the staleness/ordering anomalies. A read might return an older value than a previous read in the same logical flow; two reads might disagree on ordering. The data is correct in the limit, not at any given instant.

The cost, concretely. The lowest write latency, the highest read availability (any replica can answer immediately), and the cheapest reads (1× RUs). When you genuinely don’t care about freshness or order — only that the number is roughly right and converges — Eventual extracts the most performance and availability the system can give.

When to choose it. Counters and aggregates where approximate is fine: like counts, view counts, “people are looking at this” badges, non-critical telemetry. If a user seeing “1,204 likes” instead of “1,205” for two seconds is acceptable, Eventual is the correct, cheapest choice — and anything stronger is wasted RUs and latency. Conversely, avoid Eventual the moment the same user must read their own write (use Session), order of events matters (use Consistent Prefix), or a balance/inventory/lock must be exact (use Bounded Staleness or Strong).

Latency, throughput, availability and cost — the trade-off made numeric

The five levels are points on a curve. This section quantifies it so you can reason about the consequences of moving the dial, not just the guarantees.

The most important operational fact: consistency level changes the RU cost of reads. A point read of a 1 KB item is 1 RU at Session, Consistent Prefix and Eventual; the same read at Strong or Bounded Staleness is roughly 2 RUs, because the engine may consult multiple replicas to honour the stronger contract. On a read-heavy workload at scale, that doubling is a real, recurring cost line.

Availability deserves its own framing, because it’s where the CAP trade-off lives. Cosmos DB publishes distinct read and write availability SLAs, and the level interacts with topology:

The cost picture has three drivers, only one of which is the consistency level — but it’s a driver you control with a single setting:

The takeaway: moving from Strong/Bounded down to Session typically halves read RU charges and improves write latency and availability — so the default posture is “use the weakest level that still meets the workload’s correctness contract,” tightening only where a specific container demands it.

Overriding consistency per request

The account-level setting is the default and the ceiling. Individual operations can ask for a different level — but only in legal directions. The rule that governs everything here:

A request may relax to any level weaker than the account default. It may not request a level stronger than the account default — except that, within the account’s provisioned guarantee, you can move between Session and Bounded Staleness in the directions the account supports.

In practice the safe, always-legal move is relaxing: a Session-default account can serve a high-volume, freshness-irrelevant read at Eventual to save RUs and latency. You cannot tighten beyond the default for a structural reason — the machinery for a stronger contract (e.g. quorum writes for Strong) only runs if the account is provisioned for it; a single request cannot summon guarantees the account isn’t enforcing.

* The Session↔Bounded relationship has nuance per topology; the dependable, portable pattern is to set the account at the strongest level any workload needs and relax per request for the rest.

Setting a per-request level in the SDK is a request option. The .NET SDK pattern:

// Relax a single, freshness-irrelevant read to Eventual on a Session-default account
var requestOptions = new ItemRequestOptions
{
    ConsistencyLevel = ConsistencyLevel.Eventual
};

ItemResponse<ViewCount> response = await container.ReadItemAsync<ViewCount>(
    id: "video-42",
    partitionKey: new PartitionKey("video-42"),
    requestOptions: requestOptions);

// RU charge of this read — observe the ~1 RU baseline vs ~2 RU at Strong/Bounded
double ruCharge = response.RequestCharge;

The pattern this enables is powerful: set the account default to the strongest level your most demanding container needs, then relax per request for everything else. Strict workloads get their guarantee; loose workloads pay only the cost they need — instead of forcing the whole account to the strictest level and paying 2× read RUs everywhere.

Session token: how Session actually works

Session consistency is the default and the most-used level, so its mechanics deserve a dedicated section — most “stale read” incidents on a Session account trace back to a mishandled session token.

A session token is an opaque string the service returns on every response (header x-ms-session-token) encoding how far this session has progressed per partition. On the next request the SDK sends it back, and the service serves the read from a replica that is at least as caught up as the token says — which is what delivers read-your-own-writes. The critical scoping fact: the token is tracked per CosmosClient instance, so all operations through one client object share a session automatically.

The failure mode is crossing a session boundary without carrying the token:

To preserve the guarantee across a session boundary, capture the token from the write response and pass it into the read request:

// 1) After a write, capture the session token from the response
ItemResponse<Cart> write = await container.UpsertItemAsync(cart, new PartitionKey(cart.UserId));
string sessionToken = write.Headers.Session;   // carry this to wherever the read happens

// 2) On the read (possibly a different server/instance), supply the token
var readOptions = new ItemRequestOptions { SessionToken = sessionToken };
ItemResponse<Cart> read = await container.ReadItemAsync<Cart>(
    cart.Id, new PartitionKey(cart.UserId), readOptions);
// Now the read is guaranteed to see the just-written cart, even cross-instance

Two anti-patterns cause most Session-consistency surprises, and both are about object lifetime and token flow:

Multi-region behaviour, failover and conflicts

A consistency level is only half the story; the other half is the account’s region topology. The same level behaves differently across three topologies, and failover is where loose levels surprise people.

Failover is the moment a read region is promoted to accept writes (planned, or automatic on a regional outage). What happens to your reads depends on the level:

That last row is the production trap: on Eventual (or even Consistent Prefix), after a failover a reader may land on a behind replica, so a value that “advanced” before the failover appears to regress. If your app baked in an assumption of monotonic progress without a level that guarantees it, this is where the bug surfaces — and only during an actual failover, exactly when you can least afford a surprise.

Multi-region write introduces conflicts: two regions accept a write to the same item at nearly the same time, and the system must reconcile them. You choose the policy:

The decision rule: if you enable multi-region write for active-active latency/availability, you have accepted Session-or-weaker consistency and signed up to handle conflicts — design the conflict policy deliberately, don’t let LWW silently discard a write you needed to merge.

Architecture at a glance

Picture a single logical item — a user’s cart — in a Cosmos DB account spanning two regions. Trace a write then a read, and you see where each level draws its line. A client in the West region writes; the SDK routes it to the local write replica set, which commits to a quorum of local replicas (the durability and ordering boundary), then streams the change asynchronously across the backbone to East’s replicas (the amber replication queue). A read from East is served from East’s local replica — fast, never crossing the ocean — but whether it sees the West write depends entirely on the level: Strong forces the read to confirm it has the globally-latest version (paying coordination cost, forbidding active-active); Bounded Staleness lets East be behind, but only within K versions or T seconds; Session keeps the writer’s own reads fresh via the session token; Consistent Prefix guarantees East sees a coherent, never-reordered prefix; Eventual lets East catch up whenever the queue drains.

The diagram below lays this out left→right: the client/SDK zone (per-request override and session token), the write region replica set (quorum commit — the freshness source of truth), the cross-region replication queue (the lag every relaxed level trades on), the read region replica set (where a local, possibly-stale read is served), and the control plane (account default + failover policy governing it all). The numbered badges mark the five places a consistency decision or failure bites: the per-request override, the quorum-commit cost, the replication lag, the local-read staleness, and the failover/conflict moment. Read the legend as “what each number means for freshness and what to do about it.”

Real-world scenario

ShopRift, a mid-size online retailer (fictional, but the shape is real), ran a single-region Cosmos DB account at the default Session and was happy — until a Black Friday plan called for a second region in another geography to cut read latency for a new market and survive a regional outage. The platform lead, reasoning “more regions means more risk of inconsistency, let’s be safe,” flipped the account to Strong and enabled the second region. Two things broke in staging within an hour.

First, the read RU bill roughly doubled. ShopRift’s catalogue browse path is overwhelmingly reads — product pages, search, category listings — and every point and query read now cost ~2× the RUs it did at Session. Their provisioned throughput, sized for Session read costs, started throttling (HTTP 429) under normal staging load. Second, worse: when they tried to enable multi-region write to let the new region accept cart writes locally (the whole point of adding it), the portal refused — Strong is incompatible with multi-region write. They were paying for a second region they couldn’t write to.

The team brought in a consistency review. The exercise was simply to map each container to the weakest level that still met its correctness contract, instead of forcing the whole account to one extreme:

• Catalogue (read-mostly, staleness-tolerant): a product description being 2 seconds stale is invisible to users. Eventual (relaxed per request on the read path). Read RUs dropped back to 1×.
• Cart and profile (user-scoped, read-your-own-writes): the user must see their own cart updates. Session — and with multi-region write enabled, the cart could now be written locally in either region, with a custom conflict-resolution stored procedure that merges cart line-items rather than letting Last-Writer-Wins silently discard one region’s addition.
• Inventory decrement (must never oversell): this is the one container where stale reads are a genuine defect. They kept this on Bounded Staleness with a tight window (K and T sized to their tolerance), accepting the ~2× read cost on the small, hot inventory container only — not the whole account.

The account default was set to the strongest level any container needed (Bounded Staleness), the rest relaxed per request to Session or Eventual. Net result: read RUs on the dominant catalogue path returned to baseline (halving the throttling), the second region became a real active-active write region for carts, and the one genuinely strict workload — inventory — kept a bounded-freshness guarantee on its small footprint. The lesson: “safe” is not a synonym for “Strong everywhere.” Safe is matching each workload to its actual contract — almost always a mix of levels, dominated by Session.

Advantages and disadvantages

The honest two-column view of moving the dial in each direction:

When each side matters: the stronger column wins for correctness-critical, single-region, low-to-moderate-read data where a stale read is a defect — ledgers, locks, inventory that must not oversell. The weaker column wins for read-heavy, latency-sensitive, multi-region, staleness-tolerant data — catalogues, feeds, counters, telemetry — the majority of most apps’ traffic by volume. The mature posture: live mostly in the weaker column (Session as default) and surgically tighten the few containers that need it, rather than paying the stronger column’s tax account-wide.

Hands-on lab

This lab is free-tier-friendly — a Cosmos DB account with free tier enabled gives you 1,000 RU/s and 25 GB at no cost (one per subscription). You’ll create an account, read and change its consistency level, configure a Bounded Staleness window, and observe the per-request override and RU difference. All commands are copy-pasteable in Cloud Shell.

Step 1 — Create a resource group and a free-tier Cosmos DB account (NoSQL API).

RG=rg-cosmos-consistency-lab
LOC=eastus
ACCT=cosmosconsist$RANDOM   # must be globally unique, lowercase

az group create --name $RG --location $LOC

# Free tier (one per subscription), default consistency Session
az cosmosdb create --name $ACCT --resource-group $RG \
  --locations regionName=$LOC failoverPriority=0 isZoneRedundant=False \
  --default-consistency-level Session \
  --enable-free-tier true

Expected: the account provisions in a few minutes. --default-consistency-level Session sets the account default (the ceiling for relaxation).

Step 2 — Inspect the current consistency policy.

az cosmosdb show --name $ACCT --resource-group $RG \
  --query "consistencyPolicy" -o json
# => { "defaultConsistencyLevel": "Session", "maxIntervalInSeconds": ..., "maxStalenessPrefix": ... }

The maxIntervalInSeconds and maxStalenessPrefix fields only take effect when the level is Bounded Staleness, but they’re always present.

Step 3 — Change the account to Bounded Staleness and set the K/T window.

# K = max staleness prefix (versions), T = max interval (seconds)
# Single-region minimums: K >= 10, T >= 5
az cosmosdb update --name $ACCT --resource-group $RG \
  --default-consistency-level BoundedStaleness \
  --max-staleness-prefix 100 \
  --max-interval 10

Expected: reads now guaranteed within 100 versions OR 10 seconds of the latest, whichever is hit first. Try setting --max-interval 2 and observe the error — it’s below the single-region minimum of 5 seconds.

Step 4 — Create a database and container to read against.

az cosmosdb sql database create --account-name $ACCT --resource-group $RG --name appdb

az cosmosdb sql container create --account-name $ACCT --resource-group $RG \
  --database-name appdb --name carts \
  --partition-key-path "/userId" --throughput 400

Step 5 — Observe the per-request override concept. The RU difference between a Strong/Bounded read and an Eventual read is visible in the RequestCharge of any SDK call (the ConsistencyLevel request option in Step from the SDK section above relaxes a single read). In the Data Explorer, run a query and check the Request Charge shown in the Query Stats — note the baseline; on a Strong/Bounded account, point reads land near ~2 RU versus ~1 RU at Session/Eventual.

Step 6 — Set it back to Session (the sensible default) before you finish.

az cosmosdb update --name $ACCT --resource-group $RG \
  --default-consistency-level Session

Step 7 — Teardown (free tier costs nothing, but clean up anyway):

az group delete --name $RG --yes --no-wait

The Bicep equivalent of the consistency policy, so this is reproducible in IaC (drop into the properties of a Microsoft.DocumentDB/databaseAccounts@2024-05-15 resource):

consistencyPolicy: {
  defaultConsistencyLevel: 'BoundedStaleness'  // strongest level any container needs
  maxStalenessPrefix: 100      // K: versions (single-region min 10, multi-region min 100,000)
  maxIntervalInSeconds: 10     // T: seconds (single-region min 5, multi-region min 300)
}

Common mistakes & troubleshooting

The recurring production failure modes — symptom, root cause, how to confirm, and the fix. This is the section to keep open during an incident.

Two diagnostic distinctions that save the most time:

Best practices

• Default to Session. It is the right answer for the large majority of workloads. Only deviate for a container with a demonstrated stronger or weaker need.
• Choose the weakest level that meets each workload’s correctness contract — not the strongest “to be safe.” Over-tightening costs ~2× read RUs, higher latency, and lost availability you may need.
• Set the account default to the strongest level any container needs, then relax per request for everything else. Don’t force the whole account to the strictest setting.
• Use a singleton CosmosClient for the application’s lifetime. Recreating it per request breaks Session’s automatic token tracking and wastes connections.
• Propagate the session token across tier boundaries (web→worker, region→region) whenever read-your-own-writes must hold outside a single client instance.
• Never enable multi-region write without a deliberate conflict-resolution policy. Default Last-Writer-Wins silently discards data; use a custom merge where you need union semantics.
• Express Bounded Staleness as a real SLA number. If you can’t name “how stale is too stale,” you probably want Session, not Bounded Staleness.
• Use Consistent Prefix, not Eventual, when order matters at all. It’s the same cost with an ordering guarantee — there’s no reason to lose order for free.
• Test under replication lag, not just against a single-replica emulator. Consistency bugs are invisible without lag.
• Right-size RU/s after, not before, choosing the level, because the level changes read cost — measure the real RequestCharge.
• Document each container’s chosen level and why in your IaC, so the next engineer doesn’t “tighten to be safe” and double your bill.
• Treat failover as a first-class test, especially on Eventual/Prefix, to catch monotonic-progress assumptions before they bite in a real outage.

Security notes

Consistency level is about correctness and timing, not access control — but a few security-adjacent points matter. Choosing a stronger level does not protect against unauthorised reads; it only governs freshness. Access is enforced separately by Azure RBAC / data-plane role assignments and resource tokens, and you should disable key-based auth in favour of Microsoft Entra ID identities where possible. Network isolation is independent of consistency too: lock the account behind a Private Endpoint so traffic stays on the Azure backbone (see Azure Private Endpoint vs Service Endpoint: Secure PaaS Access) and disable public network access. Encryption at rest is on by default (with optional customer-managed keys), and TLS protects data in transit, regardless of level. One subtle interaction: in a multi-region-write topology, a custom conflict-resolution stored procedure runs server-side with the engine’s privileges — review its logic as you would any code with data-modifying power, because a flawed merge can corrupt or leak across a partition boundary. Finally, the session token is not a secret, but it is request metadata you forward between tiers — don’t log it indiscriminately, and don’t trust a client-supplied token to grant access (it governs freshness, never authorisation).

Cost & sizing

The bill has three levers, and consistency is the one most often pulled in the wrong direction.

Concrete intuition on the consistency lever: a read-heavy service doing ~2,000 point reads/sec sustained costs ~2,000 RU/s at Session/Eventual but ~4,000 RU/s at Strong/Bounded for the same reads. At the standard single-region rate (~$0.008 per 100 RU/s-hour, ~₹0.65 at ~₹83/USD), that workload runs on the order of ~$115/month (~₹9,500) at Session versus ~$230/month (~₹19,000) at Strong — a clean doubling driven solely by the dial, before any storage or extra-region cost. Free tier (1,000 RU/s + 25 GB, one per subscription) covers small workloads and the lab at zero cost; serverless (pay per RU consumed) suits intermittent workloads and makes the consistency-cost difference pay-as-you-go. The sizing rule: pick the level by correctness need first, size RU/s to the measured charge, and revisit the level if the bill is dominated by read RUs on a staleness-tolerant path.

Interview & exam questions

Q1. Name Cosmos DB’s five consistency levels from strongest to weakest. Strong, Bounded Staleness, Session, Consistent Prefix, Eventual. They form a strict spectrum where each stronger level provides every guarantee of the weaker ones plus more. Maps to AZ-204 and DP-420.

Q2. What exactly does Strong consistency guarantee, and what does it cost? A read always returns the most recent committed write globally (linearizability). It costs the highest write latency, ~2× read RUs, is incompatible with multi-region write, and reduces write availability during a partition because it sacrifices availability to keep its promise (the CAP trade).

Q3. What is the precise guarantee of Session consistency, and why is it the default? Within a single session it gives read-your-own-writes, monotonic reads/writes, and writes-follow-reads; across sessions it gives no freshness promise. It’s the default because that per-user guarantee is exactly what most web apps need, at 1× read RU and low latency.

Q4. How does Bounded Staleness let you tune the trade-off? You set K (max staleness prefix in versions) and T (max staleness interval in seconds); reads lag the latest write by at most whichever is reached first, and order is preserved. It sits between Strong and Session — fresher than Session within a hard bound, but at ~2× read RU.

Q5. Why can a per-request override relax but not tighten beyond the account default? Because the replication machinery for a stronger contract (e.g. quorum writes for Strong) only runs if the account is provisioned for that level. A single request cannot summon guarantees the account isn’t enforcing, so you can only ask for weaker.

Q6. Which levels are compatible with multi-region (active-active) write, and which are not? Session, Consistent Prefix and Eventual are allowed. Strong and Bounded Staleness are not, because two regions cannot both guarantee “latest” simultaneously. Enabling multi-region write therefore caps you at Session-or-weaker and introduces conflict resolution.

Q7. A user updates their profile and immediately doesn’t see the change on a Session-default account. What’s the most likely cause? The read crossed a session boundary without the session token — typically a new CosmosClient per request, or a read on a different server/instance than the write. Fix with a singleton client and by propagating the token.

Q8. What’s the difference between Consistent Prefix and Eventual? Both can be stale at the same cost (1× read RU), but Consistent Prefix guarantees reads never see writes out of order (you always see a valid prefix of history), whereas Eventual gives no ordering guarantee. Choose Consistent Prefix whenever order matters at all.

Q9. After a regional failover, a counter that was increasing appears to decrease. Why, and how do you prevent it? On Eventual (or Consistent Prefix), the promoted region’s replica may have been behind, so progress appears to regress. Prevent it by using Session or stronger for reads that assume monotonic progress, or by designing the app to tolerate non-monotonic reads.

Q10. How does consistency level affect Request Unit charges? Reads at Strong and Bounded Staleness cost roughly twice the RUs of the same read at Session, Consistent Prefix or Eventual, because the engine may consult multiple replicas to honour the stronger guarantee. This makes the level a direct cost lever on read-heavy workloads.

Q11. You enable multi-region write and one region’s update to an item silently disappears. What happened and how do you fix it? A write-write conflict was resolved by the default Last-Writer-Wins policy, which kept the higher-timestamp write and discarded the other. Fix by implementing a custom conflict-resolution stored procedure that merges, or by reading the conflicts feed and reconciling manually.

Q12. When is Strong actually the right choice? In a single-region account for data where a stale read is a correctness defect even for milliseconds — a financial ledger balance, a distributed lock/leader record, an inventory decrement that must never oversell — and where you don’t need multi-region write or the availability of looser levels.

Quick check

1. Order the five consistency levels from strongest to weakest.
2. True or false: a per-request override can make a single read stronger than the account default.
3. Which consistency levels are incompatible with multi-region (active-active) write?
4. On a Session-default account, what is the single most common cause of a failed read-your-own-writes, and the fix?
5. What are the two bounds you configure for Bounded Staleness, and how do they combine?

Answers

1. Strong → Bounded Staleness → Session → Consistent Prefix → Eventual.
2. False. A request can only relax (weaken); it cannot exceed the account’s provisioned guarantee, because the stronger contract’s machinery may not be running.
3. Strong and Bounded Staleness — both require a single source of truth for “latest,” which active-active writes break. Session, Consistent Prefix and Eventual are allowed.
4. A session-token boundary crossed without propagating the token (new CosmosClient per request, or read on a different instance than the write). Fix: singleton client; capture Headers.Session after the write and pass it as SessionToken on the read.
5. Max staleness prefix (K, in versions) and max staleness interval (T, in seconds); they combine as an OR — the system enforces whichever is reached first (single-region minimums K≥10, T≥5).

Glossary

• Consistency level — The contract defining how stale and how ordered a read may be; selectable per account and per request.
• Strong — Linearizable consistency: every read sees the latest committed write globally; highest cost, single-region.
• Bounded Staleness — Reads lag the latest write by at most K versions or T seconds; tunable freshness with a hard cap.
• Session — Read-your-own-writes and monotonic guarantees within one session; the default and the right choice for most apps.
• Consistent Prefix — Reads are always a valid (possibly old) prefix of write history; order guaranteed, freshness not.
• Eventual — Replicas converge eventually with no order or freshness guarantee; cheapest, fastest, loosest.
• Session token — Opaque marker (header x-ms-session-token) encoding a session’s progress; what makes Session consistency work; must be propagated across client/instance boundaries.
• Request Unit (RU/s) — Normalised throughput currency; Strong/Bounded reads cost ~2× the RUs of looser levels.
• Max staleness prefix (K) — The version-count bound for Bounded Staleness.
• Max staleness interval (T) — The time bound (seconds) for Bounded Staleness.
• Multi-region write — Active-active topology where multiple regions accept writes; capped at Session-or-weaker; introduces conflicts.
• Conflict resolution — How simultaneous multi-region writes are reconciled: Last-Writer-Wins, custom stored procedure, or manual conflict feed.
• Last-Writer-Wins (LWW) — Default conflict policy that keeps the write with the highest value of a chosen property (usually timestamp) and discards the rest.
• Failover — Promotion of a read region to accept writes (planned or automatic); changes which replica answers and can expose staleness on loose levels.
• Linearizability — The property that the system behaves as if a single copy of the data processed all operations in one global order; what Strong provides.

Next steps

• Decide which Cosmos DB API your data model fits before tuning consistency — start with Choosing a Cosmos DB API: NoSQL vs MongoDB vs Cassandra vs Gremlin vs Table Decoded.
• Build an ordered, event-driven pipeline whose ordering rests on the Consistent Prefix guarantee with Cosmos DB Change Feed in Action: Event-Driven Pipelines with Azure Functions and the Processor.
• Wire serverless compute to Cosmos and inherit the consistency you set here in Wiring Azure Functions to Storage Queues and Cosmos DB: A Hands-On Input/Output Binding Tutorial.
• Lock the account onto the private backbone before going to production with Azure Private Endpoint vs Service Endpoint: Secure PaaS Access.
• Instrument RU charges, throttling (429) and per-region latency so your consistency choice is measured, not assumed, using Azure Monitor and Application Insights: Full-Stack Observability.