Skip to content

Search API

Edit page

You can search for documents by using the SEARCH method:

SEARCH /bank/

A search answers 200 with the hits, how many came back and how many match:

{
"hits": [ { "accountNumber": 121931, "age": 24, "_id": 1, "_version": 1 } ],
"count": 1,
"total": 1000,
"took": 0.0012
}
  • hits are the documents, each with its _id and _version. With comments=true each also carries #docid, #shard, #rank, #weight and #percent.
  • count is the number of hits in the answer, and total is the number of documents that match (after a collapse, the hits that are left).
  • took is the search’s time in seconds (human=true writes it as a string such as 1.2 ms).
  • aggregations is there when the body asks for aggregations.

A search over an index that does not exist, or a pattern that matches none, is not an error: it answers 200 with no hits.

The query string and the body of a SEARCH (or COUNT) are both read. The body keys start with an underscore. A body _query, _limit, _offset and _check_at_least replace the parameters of the same name; a body _sort and sort parameters add up.

ParameterBody keyMeaning
q, query_queryThe query. A parameter is a query string and may be repeated: the queries are ANDed. The body takes the Query DSL. With neither, every document matches.
limit_limitThe most hits to return (10).
offset_offsetThe hits to skip (0).
sort_sortThe order of the hits; the parameter may be repeated.
check_at_least_check_at_leastThe least documents to examine; the node reads every match when the search has aggregations.
collapse, collapse_maxSee Collapsing results.
selector_selectorKeeps one part of each hit (accountNumber, contact.city).
volatileOpens the index for writing, so the search sees the writer’s latest view.
pretty, human, commentsHow the answer is written; see Options.
spelling, synonyms, icaseRead and ignored.

Sources: src/server/search_views.cc:2340-2470 (the parameters), src/database/handler.cc:1140-1230 (the body keys), src/server/search_views.cc:1932-2090 (the answer).

limit and offset page through the hits:

SEARCH /bank/?limit=3&offset=2&sort=-accountNumber

sort takes a field (ascending), a field with a leading - (descending), and may be given more than once, the later ones breaking ties. A body _sort takes a field, a list of fields, or an object with _order: {"balance": {"_order": "desc"}} (Exploration).

SEARCH /bank/?limit=3&sort=age&sort=-accountNumber

A repeated q ANDs its queries:

SEARCH /bank/?q=age:30&q=eyeColor:blue&limit=2

limit=0 asks for no hits, only the total, and selector keeps one part of each hit:

SEARCH /bank/?q=age:30&limit=2&selector=accountNumber

COUNT takes the same query and answers only the total:

COUNT /bank/?q=age:30

collapse keeps the best hit for each distinct value of a field, and drops the rest. Documents without a value for the field are never collapsed. Here the account holders are collapsed by eye color, so one account of each color comes back:

SEARCH /bank/?collapse=eyeColor

The hits keep their order (by relevance, or by sort), total counts the hits that are left, and limit and offset apply to them. collapse_max keeps more than one hit per value (it is 1 by default).