Consistency level is set per request, yet most codebases set it once in driver config and forget it. That default decides what your application sees during a node loss, a network partition, or a slow disk. This post covers how to choose it on purpose.
The rule: R + W > RF
With replication factor RF, a read at level R and a write at level W are guaranteed to overlap on at least one replica when R + W > RF. With RF=3, QUORUM is 2. QUORUM writes plus QUORUM reads give 2 + 2 > 3, so a read sees the latest acknowledged write, provided the replicas respond correctly.
Two caveats we see in audits:
- The overlap guarantee covers acknowledged writes. A write that timed out at the client may still have landed on some replicas. Treat timeouts as unknown outcomes, not failures.
- Overlap does not give you linearizability. Concurrent writes resolve by timestamp (last write wins). If you need compare-and-set, that is a lightweight transaction, with its own cost.
The common levels
| Level | Replicas that must answer (RF=3) | Typical use |
|---|---|---|
| ONE / LOCAL_ONE | 1 | Telemetry reads where staleness is tolerable |
| QUORUM | 2 across all DCs (majority of total replicas in multi-DC) | Single-DC clusters |
| LOCAL_QUORUM | 2 in the coordinator's DC | Default for multi-DC |
| EACH_QUORUM | Quorum in every DC (writes only) | Rare; fails if any DC is unreachable |
| ALL | 3 | Almost never; one down node fails the request |
Why LOCAL_QUORUM in multi-DC
In a two-DC cluster with RF=3 per DC, QUORUM needs 4 of 6 replicas. That means at least one cross-DC round trip on most requests, and tens of milliseconds added to p99. LOCAL_QUORUM needs 2 of 3 in the local DC and stays off the WAN.
The trade-off is honest: with LOCAL_QUORUM on both sides, a write in DC1 is not guaranteed visible to a LOCAL_QUORUM read in DC2 immediately. Replication to DC2 is asynchronous from the client's view. If your application can read its own writes only in the same DC, pin each session to one DC. Make sure the driver uses a DC-aware load-balancing policy with the local DC set explicitly, and does not fail over to remote DCs silently.
What read repair does (and does not do)
When a read at QUORUM finds replicas disagreeing, the coordinator resolves the newest value, returns it, and writes it back to the stale replicas. That is blocking read repair. It fixes only the data that was read, which is why it does not replace scheduled anti-entropy repair. Cold data that nobody reads stays divergent until a full repair runs. See our repair and compaction hygiene post for scheduling.
Two practical points:
- Hints and read repair narrow the window of divergence. Neither covers a node that was down longer than the hint window (3 hours by default,
max_hint_window). After that, you need a repair. - Deleted data depends on this. If a replica missed a tombstone and
gc_grace_secondselapses before repair, the deleted data can return. This is the main reason repair cadence must stay inside gc_grace.
Choosing per query
- Start with LOCAL_QUORUM for reads and writes on anything you cannot lose.
- Drop reads to LOCAL_ONE only for data where a stale answer is harmless and measured latency justifies it. Measure first.
- Use SERIAL or LOCAL_SERIAL only for LWTs, and expect several round trips.
- Do not use ALL or EACH_QUORUM on a hot path. They convert one node failure into an outage.
Check what you are really running
- Grep the driver config and every call site for explicit consistency overrides. Mixed levels are common after years of changes.
- Confirm RF per keyspace with
DESCRIBE KEYSPACE. A keyspace still on SimpleStrategy in a multi-DC cluster makes LOCAL_QUORUM behave unexpectedly. - Watch coordinator read and write latency and the unavailable and timeout counters per consistency level. A rise in
Unavailableerrors means the level demands more replicas than are up. - Test it: take one node down in staging and run your real workload. Record which requests fail.
When the model itself is the problem
If the application needs cross-row transactions or strict read-after-write across regions, tuning consistency levels will not fix it. That is a fit question, covered in our post on when Cassandra is the wrong tool.
If you want a second pair of eyes on your consistency and replication setup, a cluster review covers it along with driver configuration.