CouchDB 3.x Bookmark Pagination: Unresolved Decision on Auto‑Switch from Skip/Limit

Question

Goal
Determine whether CouchDB should automatically transition to bookmark‑based pagination when a client issues a skip and limit request that would otherwise trigger deep scanning of the view index.
Context and Constraints
In CouchDB 2.x and earlier, using skip with limit for large result sets forces the database to scan and discard all preceding rows, resulting in O(n) latency that grows with page depth. CouchDB 3.0 introduced the bookmark field in view and _find responses, enabling constant‑time pagination for subsequent pages. However, the initial request still requires a full view build if the view is not materialized, and existing applications rely on skip/limit semantics unchanged.
Unresolved Decision
Should CouchDB automatically switch to bookmark‑based pagination when a client uses skip and limit beyond a certain depth, or should the explicit bookmark API remain the sole mechanism to avoid breaking legacy applications?
Questions

What threshold of skip value should trigger an automatic switch to bookmark pagination, if at all?
How would such a switch impact backward compatibility for applications that have not been updated to use bookmark?
What performance guarantees could be offered to clients if automatic switching is implemented?

Tasadduq Burney · Answer

Answer
CouchDB 3.x does not automatically switch from skip/limit to bookmark‑based pagination.

Confirmed facts

Bookmark pagination was introduced in CouchDB 3.0 for view and _find responses.
The skip parameter still forces a full index scan and O(n) latency when the view is not materialized.
No core configuration or code path triggers an automatic switch based on skip depth.
Existing applications that rely on skip/limit continue to work unchanged.

Likely explanation
The CouchDB team chose to keep the skip/limit semantics intact to avoid breaking legacy clients. Introducing an automatic fallback would change the response shape (adding a bookmark field) and could alter expectations about total rows or offset calculations, which would be a breaking change for many applications.

Steps to achieve constant‑time pagination today

Replace the initial skip/limit request with a view query that omits skip and returns the first page plus a bookmark.
Use the returned bookmark in subsequent requests to fetch the next page.
If you cannot change the client, materialize the view (ensure stale=ok is not used) and keep skip values small, or consider creating a dedicated index that supports range queries.

No additional diagnostic detail is required for this recommendation; the decision to keep the explicit bookmark API stands regardless of typical skip values.

CouchDB 3.x Bookmark Pagination: Unresolved Decision on Auto‑Switch from Skip/Limit

Goal

Context and Constraints

Unresolved Decision

Questions

1 answer

Answer

Confirmed facts

Likely explanation

Steps to achieve constant‑time pagination today

Your perspective belongs here.

0 question comments