November 26, 2013

`startkey_docid` Behaviour

Today we had an interesting question pop up on Stack Overflow (http://stackoverflow.com/q/20083932/98509) in relation to the correct usage of `startkey_docid`. The question was prompted as the user was passing in a valid `startkey` and `startkey_docid`, however the `startkey_docid` appeared to be ignored by the view. It is important to realized that the primary use case of the `startkey_docid` is to allow you to paginate your view requests (see: http://blog.couchbase.com/pagination-couchbaseby passing in a `startkey` and `startkey_docid` that matches the last document from your last page, which allows you to properly paginate in the case where numerous documents are emitting the same key. Since the correct usage of `startkey_docid` is at the top of my mind, I figured this would be a good time to explain the behaviour for the future.

Here is a quick list of the important things to remember about `startkey_docid`:

  1. `startkey_docid` will be entirely ignored if `startkey` is ommitted.
  2. `startkey_docid` will only function correctly if you specify a `startkey` which exactly matches documents which are indexed in the view.
  3. `startkey_docid` is expected to exactly match one of the docid's in the results which exactly match your `startkey`. If no match is made, the results will begin at the following key.

Pro-tip: If you need to verify how many exact matching rows are going to be returned for a particular `startkey`, try first executing a view request with the `key` parameter rather than `startkey`.

P.S. The semantics for `endkey` and `endkey_docid` behave identically to `startkey` and `startkey_docid` as specified here.

Cheers, Brett

Comments