Stale view results when using stale=ok in CouchDB

Question

Goal: Choose a stale mode for CouchDB view queries that balances read latency with acceptable data freshness under fluctuating write loads.
Constraint: The application does not have a built‑in policy to automatically switch between stale=ok, stale=update_after, and stale=false, and the impact of each mode on result staleness is not quantified for the current workload pattern.
Uncertainty: Without monitoring, it is unclear how often stale=ok will return noticeably outdated rows or how delayed the asynchronous update triggered by stale=update_after becomes during peak writes.
Questions: What measurable indicators (e.g., update_seq lag, active indexer tasks) should trigger a switch from stale=ok to a fresher mode? How can latency versus staleness trade‑offs be expressed as a configurable threshold? Is there a reliable way to automate stale mode selection based on real‑time view lag?

Tasadduq Burney · Answer

Answer
With stale=ok CouchDB returns the view rows from the existing index immediately, without waiting for the indexer to catch up with recent writes. If any documents have been added, updated, or deleted after the index was last built, those changes are not reflected in the result, so the view can appear stale.
Confirmed behavior

The stale parameter only affects when the index is refreshed; it does not change how the index is stored.
CouchDB includes an update_seq field in the view response that shows the sequence number of the database up to which the index is current.
When stale=ok is used, the server may also add a warning header (X-CouchDB-Warning: stale ok) indicating that the result might be out‑of‑date.

Steps to verify stale results for a specific view

Request the view with stale=ok and note the update_seq value returned (e.g., GET /mydb/_design/ddoc/_view/myview?stale=ok).
Fetch the database’s current sequence with GET /mydb and compare its update_seq to the view’s value.
If the database’s update_seq is higher, the view is stale; repeat the request with stale=false (or stale=update_after) and check whether the row count or any field values differ.
Optionally, inspect GET /mydb/_active_tasks for indexer processes; a long‑running “indexer” task indicates that the server is still catching up.

Expressing latency vs. staleness as a threshold
Define a tolerable lag, L_max, as the maximum difference between the database’s update_seq and the view’s update_seq that your application can accept. Monitor the lag continuously; when the observed lag exceeds L_max, switch the query mode to stale=update_after (or stale=false for strong consistency).
Automating stale‑mode selection
Yes – a lightweight controller can poll /mydb and the view endpoint (with stale=ok) every few seconds, compute the lag, and dynamically add the appropriate stale parameter to subsequent requests. The controller only needs to know the application‑specific L_max; without that value it cannot decide when to switch, so please provide the maximum acceptable update_seq lag for your workload.

Stale view results when using stale=ok in CouchDB

1 answer

Answer

Confirmed behavior

Steps to verify stale results for a specific view

Expressing latency vs. staleness as a threshold

Automating stale‑mode selection

Your perspective belongs here.

1 question comment