Revisit cursors, offset and totalResults


The SPI does not clearly explain the semantics of these three concepts, and their interaction. For example, when using a cursor, is offset relative to the cursor or absolute?

Release Notes



Andreas Neumann
February 12, 2019, 7:17 PM

Semantics for limit and offset, and cursors:

  1. if the search request does not contain a cursor, the limit and offset can be given. The response will contain at most limit results. The response will also contain an estimate of the total number of results. If that is greater than offset + number of results, then there are more results.

  2. if the search request requests a cursor, it will only be returned if |limit| results are returned, and there are more results following these. This cursor can then be passed to a following search.

  3. If a cursor is provided in the search request, then limit and offset should not be provided. Instead, the search will resume where the previous search (that returned the cursor) stopped, and it will use the same limit. That is, if the previous search started at offset O with limit L, then this search starts at O+L, also with limit L. The search response will always contain the offset and limit that were applied to the search. 

  4. A cursor may only be requested if the offset is 0, or the search continues from a previous cursor


Your pinned fields
Click on the next to a field label to start pinning.


Andreas Neumann


Andreas Neumann