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: https://www.couchbase.com/blog/pagination-couchbase) by 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

Author

Posted by Brett Lawson, Principal Software Engineer, Couchbase

Brett Lawson is a Principal Software Engineer at Couchbase. Brett is responsible for the design and development of the Couchbase Node.js and PHP clients as well as playing a role in the design and development of the C library, libcouchbase.

All Posts

4 Comments

  1. Michael November 27, 2013 at 6:18 pm

    Brett, in the stackoverflow example those 3 conditions are met and the first 3 keys are identical. Even using your Pro-tip the 3 identical keys are being returned. Could you respond on stackoverflow how that case maynot be meeting one of the 3 criteria? It seems that it is, but maybe there is a detail that is missing.

    1. Brett Lawson November 27, 2013 at 6:29 pm

      In your StackOverflow question, your startkey does not exactly match an entry from the view. In this case, startkey_docid will essentially be ignore as mentioned in point #2 and the end of #3.
      Cheers, Brett

  2. Frederic Laub September 2, 2014 at 10:07 am

    Lost nearly a day on that. Adding this to the doc would be great for new couchbase users!
    Anyway Thanks a lot!
    Fred

Leave a reply