Sort and pagination #

Control which documents come back and in what order — sort, from/size, search_after/search_before, and total-hit accounting.

POST /my-collection/_search

Sort #

sort is an array of sort clauses evaluated in order; the first clause that produces a difference decides the order.

Parameters #

• field
  (Required, string) The field to sort by. Two pseudo-fields are always available: _score (relevance, descending by default) and _doc (index order — the cheapest possible sort).
• order
  (Optional, asc | desc) Sort direction. When omitted the engine sorts descending for _score and ascending for regular fields.
• missing
  (Optional, first | last; the gateway also accepts the Elasticsearch spellings _first / _last) Where documents without a value for the field land, independent of the sort direction. Default: last. Documents whose keys tie (including two missing values) break the tie by internal doc order, so pages are repeatable.

Sorting on an indexed field lets the engine skip documents that cannot make the cut (early termination); "_doc" and index-time sorted fields (see field parameters) are the fastest.

Pagination #

• from
  (Optional, integer, default: 0) Offset of the first hit to return.
• size
  (Optional, integer, default: 10) Number of hits to return. 0 with aggregations skips hit assembly entirely.
• track_total_hits
  (Optional, boolean | integer) Whether to compute the exact hit count. false skips counting when you only need the page; a number caps the counting work. The gateway accepts the Elasticsearch form, default cap 10000.
• collect_size
  (Optional, integer) Upper bound on candidate documents collected before ranking — a guard rail for very broad queries.

Deep from paging re-ranks everything before the offset. Prefer cursors:

• search_after
  (Optional, array) Return the rows that follow the given sort-key tuple. Take the tuple from the last hit of the previous page (sort values of that hit) and pass it back.
• search_before
  (Optional, array) The mirror image — the rows that precede the tuple. Together with search_after this enables bidirectional cursored paging.

For a stable view across pages, run the search against a point-in-time snapshot (pit — see API conventions).

Examples #

Cheapest first page of everything, newest first:

Cursor to the next page with the last hit’s sort tuple — the engine answers the rows strictly AFTER the tuple:

The first page’s newest document is S120 (epoch 1745276400000); the cursor page starts at the second-newest. A multi-key sort array gives the cursor a unique tuple per document (see the wasm note below about float-typed single keys).

Notes #

• Sorting by a field that is only in the document source (not indexed, not a column) forces full materialization — index the field or accept the cost.
• The gateway also accepts the Elasticsearch shorthand forms ("sort": ["date"], "sort": [{"date":"asc"}]) and normalizes them to the canonical clause above.