Query

One word is already
a query

A bare word searches the index’s default fields. Name a field to narrow it, in the field:value shape Lucene, Elasticsearch and Solr made familiar.

  • Words reach every default field Several words are ORed, so the loosest useful query is one you already know how to write.
  • Familiar on first sight Ranges with TO, boosts with ^, groups in parentheses: if you know Lucene, you know most of it.
  • An id skips the index The id alone, under the source’s own name for it, is answered straight from the key-value store.
books · total_hits
*16,559
dune23
title:dune16
title:dune AND author:herbert8
book_id:714161 Dune

The same parser answers a person in the REPL and an agent over MCP: one grammar, whoever asks.

Text fields

Exact, approximate
or unfinished

Quote words to hold them in order, loosen the phrase by a few words, or leave the last one unfinished.

  • Phrases, in order summary:"time travel" finds the two words side by side, nowhere else.
  • Slop for the near misses ~N lets up to N other words stand between them.
  • Prefixes, as you type title:robo* on text and string fields, and a quoted phrase completes its last word.
books · total_hits
summary:"time travel"99
summary:"time travel"~2105
summary:"time trav"*157
title:robo*13

Same summaries, each form a little wider than the one before it.

Ranges and sets

Everything ordered
can be bounded

Numbers, dates, addresses and text all have an order, so all of them take a range. Brackets include the bound, braces exclude it.

  • Dates as you write them A year, a month, 20240615 or epoch seconds, alone or as the bound of a range.
  • A set in one clause field: IN [a b c] matches any of them, across text, numbers, dates and booleans.
  • Networks by their block CIDR on an ip field is that range exactly, IPv4 or IPv6. A bare address searches every ip field.
books · total_hits
publication_date:[1960 TO 1970}666
publication_date:>=20003,881
title: IN [dune emma ulysses]20
seven sample hosts · total_hits
src:10.0.0.0/83
src:"2001:db8::/32"1
8.8.8.81
More than one clause

Narrow it without
starting again

Each clause you add keeps the ones before it, so a person or an agent refines a result step by step instead of rewriting it.

  • AND, OR, NOT In capitals, with + and - as the short way to require or exclude.
  • Groups for precedence Parentheses decide what binds to what, nested up to 64 levels deep.
  • Boosts to rank title:dune^3 weights a clause, so the field that matters most leads the hits.
books · one clause at a time
genres:"Science Fiction"2,888
AND publication_date:[1960 TO 1970}172
AND summary:planet63
-author:"Philip K. Dick"59

From 2,888 books to 59 in three additions: every step builds on the one before.

At the end of the query

One string carries
the whole request

Modifiers at the end say what comes back, in what order and how much, so the query you try is the request you send.

  • Fields, order, page return, sort, limit and offset, in any order after the query.
  • The count, or the span limit 0 counts from the index alone. min() and max() cover every match, not only the page.
  • Long arrays kept short array N keeps N elements, the matching ones first, and reports the full length.
search books · output abridged
▶ author:"Le Guin" sort publication_date
    return title,publication_date limit 5
"hits": [
  { "title": "Planet of Exile", "publication_date": "1966" },
  { "title": "Rocannon's World", "publication_date": "1966" },
  { "title": "City of Illusions", "publication_date": "1967" },
  { "title": "A Wizard of Earthsea", "publication_date": "1968" },
  { "title": "The Left Hand of Darkness", "publication_date": "1969" }
], "total_hits": 17
search books
▶ author:"Le Guin" min(publication_date) max(publication_date) limit 0
"total_hits": 17, "metrics": {
  "min": { "publication_date": "1966-01-01T00:00:00Z" },
  "max": { "publication_date": "2001-01-01T00:00:00Z" } }
Order

Every sort says
how exact it is

How a field sorts is settled from its fast column before any shard runs, and the response tells you which kind of order you got.

  • Exact on a fast column describe_index marks those fields sortable: numbers, dates, text and string declared fast.
  • Approximate, and labelled A text field without one orders the top 2 × limit matches alphabetically, and names the field in _approximate_sort.
  • Settled before it runs A field no column can order fails with cannot sort by 'FIELD' and the reason, with nothing half done.
search books · output abridged
▶ genres:"Science Fiction" AND summary:planet sort title return title limit 3
"hits": [
  { "title": "Across The Zodiac" },
  { "title": "Betrayal" },
  { "title": "Boba Fett: Crossfire" }
],
"total_hits": 800,
"_approximate_sort": "title"

Under a numeric or date sort every _score is 1.0: the order comes from the column, with no relevance computed.

Read the response

A result says
what it did

Whatever the engine set aside or adjusted arrives beside the hits, under a key that appears only when there is something to say.

  • Every dropped clause named _discarded_clauses says what was set aside and the form that works.
  • The reach of a bare word _narrowed_default_fields lists the fields it searched when a cap kept it focused.
  • Where the time went stats.timings_ms per phase, and the schema version the search ran under.
search books · output abridged
▶ author:asimov AND athor:clarke return title limit 2
"hits": [ { "title": "Foundation's Edge" }, … ],
"total_hits": 37,
"stats": { "schema": { "version": 3, … },
  "timings_ms": { "parse": 0, "walk": 0, "fetch": 0, … } },
"_discarded_clauses": [ "unknown field 'athor' — the
  clause naming it was dropped, so this result set does
  not match what the query asked for" ]

Over MCP the same query fails the call: an agent never reports rows its query did not ask for.

Tokenizers

Matched the way
people write

Each text field picks how its words meet: stemmed, folded or held whole. A query is analysed exactly as the documents were.

  • Stemmed in seven languages English, German, French, Spanish, Italian, Portuguese and Croatian, the last from a dictionary of 1.7 million word forms.
  • Accents optional The _fold variants let a plain keyboard find the accented word.
  • Chinese, Japanese, Korean No dictionary needed, with traditional and simplified, old and new kanji, Hanja and Hangul finding each other.
one field per language
en:runsfinds runningen_stem
de:Groessefinds Größede_stem_fold
fr:situeefinds situéefr_stem_fold
hr:zupanijafinds županijehr_stem_fold
zh:学习finds 學習cjk_fold
ja:読書finds 讀書cjk_ja_fold
ko:가족finds 家族cjk_ko_fold
The full grammar, generated from the parser →