Staleness depends on the read consistency level of the query
If a query is served by a replica that is behind the primary, the client may see stale results - missing points that were recently upserted, or including points that were recently deleted - and this is expected behavior in an eventually consistent system, not a bug. What the client actually sees depends entirely on the read consistency level of the query. With consistency=one, the query is sent to any healthy replica, and if that replica is lagging, the result will be stale. With consistency=majority, the coordinator queries a majority of replicas, compares their states (typically by version or operation number), and returns the freshest consistent view; a single lagging replica does not corrupt the result as long as the majority is up to date. With consistency=all, every replica must respond and the coordinator reconciles, so the result reflects the latest state across all replicas, but a single lagging or unreachable replica causes the query to fail or time out.
The mechanism behind this is that replicas catch up asynchronously via the WAL stream from the primary. There is no bound on how far behind a replica can be at any given moment; it can be milliseconds behind under normal operation or seconds to minutes behind if it is overloaded, network-partitioned, or recovering from a restart. Qdrant tracks per-shard versions so it can detect lag and reconcile when a query uses a stronger consistency level, but with consistency=one it does not attempt to reconcile - it just returns whatever the chosen replica has. The practical implication is that read-your-write is not guaranteed with the default permissive consistency, even though it may appear to work most of the time. The failure mode is intermittent and load-dependent, which makes it hard to debug. If your application upserts a point and then searches for it, and the search happens to route to a lagging replica, the point will not appear, and the user will report a bug that you cannot reproduce.
consistency=one: query any healthy replica; stale results possible if that replica is behind.
consistency=quorum/majority: query multiple replicas and reconcile; tolerant of a single lagging replica.
consistency=all: query every replica; freshest result but fails if any replica is down or slow.
Replica lag is normal: replicas catch up via WAL streaming, and lag can spike under load or after a restart.
Read-your-write: not guaranteed by default; requires wait=true on the write, a stronger read consistency, or both.
The trade-off is freshness against latency and availability. Stronger read consistency reduces staleness but costs a round trip to more replicas and makes queries fail when a replica is unhealthy. For most search workloads, consistency=one is the right default because a slightly stale index is acceptable and tail latency matters. For read-your-write scenarios - a user submits a document and then searches for it - you need either wait=true on the write or consistency=majority on the read, or both. The common mistake is assuming that a successful upsert with wait=true guarantees subsequent searches will see the point. It does not if the search is served by a replica that has not yet consumed the WAL entry, unless the read consistency forces reconciliation. The second mistake is setting consistency=all to fix staleness and then discovering that a single slow replica makes every query time out. The third mistake is treating replica lag as an anomaly to be eliminated. It is a normal property of an asynchronous replication system; the right response is to choose consistency levels that match the application's freshness requirements, not to try to make lag zero. Version note: the exact behavior of reconciliation under consistency=majority (what it compares, how it merges) has changed across releases, and the set of consistency levels supported differs. Verify on your version, and test with an artificially lagged replica rather than assuming.
Version-dependent: the replication reconciliation logic and the supported consistency levels have changed across releases. In some versions, consistency=majority compares operation numbers and returns the freshest; in others, the reconciliation is coarser. The behavior during a primary failover - specifically, whether a newly promoted primary may have missed writes that the old primary had acknowledged - depends on the write consistency factor and on the version's recovery logic. If read-your-write is a hard requirement, design it explicitly with wait=true and a stronger read consistency, and test it under replica lag and failover rather than relying on defaults.
0-2 years experience
2-5 years experience
5-8 years experience
8+ years experience
