Structured query referencedev
Every structured query is a JSON object with exactly one query arm, and every
arm is a node that composes anywhere: under boolean clauses, in filters, inside
wrappers, as a kNN filter domain, or as a fusion source. The
query language is a string syntax for the same tree.
This page is the field-level reference for the arms. It doubles as the
function reference for
the query language: a function’s name is the arm’s JSON
name and its arguments are the arm’s fields, so fuzzy(smith, field=name_s, max_edits=2) and the JSON below mean the same thing.
Queries and search operations
explains how a query selects and scores documents while operations collect
results, and links the protobuf definitions shared by JSON and gRPC.
{"query": {"match": {"title_t": "dune"}}, "fields": ["id"], "count_limit": -2}{ "found": 2, "docs": [ { "id": "b1" }, { "id": "b2" } ]}Add ?explain=request to an HTTP query to see the canonical request after
shorthand expansion.
A bare field name picks a representation by operation: text operations use
the field’s search binding, value operations (any_of, ranges, facets,
sorts, metrics) use its value binding, and f__label or f__self selects
one representation directly. See default bindings for variants
and the worked example.
Clause names
Section titled “Clause names”Any structured query object accepts an optional sibling name, unique within
its request: {"name":"recent","range":{"field":"answers.date","lte":"2012-04-08"}}.
A name references the subtree; it does not wrap it or change scores, equality,
planning or cache keys. Expression strings have no name syntax, but the
structured expr arm may be named. Row operations use domain.from_match
to select a named clause’s matching descendant rows. See
Per-row operations for eligibility and errors.
Match all and exists
Section titled “Match all and exists”{"all":true}all matches every live document with a constant score.
{"exists":{"field":"year_i"}}exists matches documents that supplied at least one accepted value for the
field. The expression shorthand is year_i:*.
Bare exists uses primary presence; an explicit selector tests that physical
representation’s presence.
match applies the field’s query-time conversion and analyzer:
{ "match": { "field": "title_t", "val": "Dune Messiah", "operator": "and" }}The HTTP dialect also accepts the field-name form:
{"match":{"title_t":"dune messiah","operator":"and"}}| Field | Meaning |
|---|---|
field |
Field to query. Required. |
val |
Value to analyze or coerce. Required. |
operator |
or (default) or and for several analyzed terms. |
min_match |
Minimum analyzed terms that must match; overrides operator and is clamped to the term count. |
case_insensitive |
Ignore simple Unicode case on indexed TEXT/STRING/ID; numeric/date ignore it. Default false. |
Text values are analyzed with the resolved field analyzer. String values use their normalizer, if configured, and match as exact terms. Numeric and date values are coerced through the same rules as indexing and matched through their columns.
IP match literals accept an address or CIDR. Host bits are masked, so
10.1.2.3/8 matches 10.0.0.0/8; 2001:db8::/32 matches that IPv6 network.
IP any_of members and range bounds require single addresses. Strict and
inclusive range bounds follow address byte order. IP fields reject
case_insensitive, prefix, wildcard/regexp, and fuzzy matching. See
IP addresses.
With case_insensitive, each analyzed TEXT token or normalized STRING/ID
value matches indexed terms that differ only in simple Unicode case: FOO
matches foo and Foo, and k matches the Kelvin sign. All indexed variants
of one token score as one word, with the exact case of the query preferred
slightly. The analyzed/normalized query token has frequency weight 1.0;
other case variants have weight 0.9. Weighted frequencies are summed per
document before BM25 saturation, with shared statistics (maximum document
frequency and summed total term frequency). A rare spelling gets no extra
IDF. These term weights do not affect field lengths. operator, min_match, and
boosts still apply over the analyzed query tokens. Filters match the same
variants without computing scores.
If analysis already erases the token’s case, ordinary term lookup and scoring
are retained. Case expansion is slower than using a folding TEXT variant such
as _t, _un, or _wl; prefer those for frequent case-blind matching.
Alternates come from the token after query-time analysis, without analyzing
them again. Case-preserving stemmed fields can therefore be lopsided: KStem
stems only lowercase words, so ponies can become pony while PONIES stays
PONIES; case expansion cannot bridge the different stems.
Numeric and date fields ignore the flag. Simple case folding is one-to-one,
so sharp s (U+00DF) does not match SS. For frequent case-blind STRING matching,
prefer a STRING normalizer with
lowercase or nfkc_cf, so ordinary match uses an exact term lookup.
Exact membership (any_of)
Section titled “Exact membership (any_of)”any_of matches any listed value in the value representation. With the
authors collection from Documents and values:
{ "query": { "any_of": { "field": "author_name", "values": ["Neal Asher"] } }, "fields": ["id"], "count_limit": -1, "sort": "id"}{ "found": 3, "docs": [ { "id": "b1" }, { "id": "b2" }, { "id": "b4" } ]}| Field | Meaning |
|---|---|
field |
Field to query through its value binding, or an explicit selector. Required. |
values |
Exact values; any matching value admits the document. |
STRING, TEXT, and ID exact membership requires indexed terms. Numeric, boolean, and date representations can use their columns. DATE members are exact instants in the field’s unit: an ISO member uses its floored start, even for a partial date. Members outside the stored date domain are dropped. Match/range date literals retain their granularity windows.
STRING literals are whole values and use the same normalizer as ingest. TEXT
literals use exact token membership: each value must analyze to at most one
term. For example, author_name__self with "Neal!" looks up neal and
matches all six books. A value producing zero terms matches nothing. For
multiple terms, use match, phrase, or a whole-value string variant.
The expression forms are field:=value and field:=(v1, v2); see
exact values.
Boolean
Section titled “Boolean”{ "boolean": { "required": [ {"match":{"title_t":"dune"}} ], "filter": [ {"range":{"field":"year_i","gte":1960}} ], "optional": [ {"match":{"author_s":"Herbert"}} ], "prohibited": [ {"match":{"status_s":"withdrawn"}} ], "min_match": 0 }}| Field | Meaning |
|---|---|
required |
Must match and contributes to score. |
filter |
Must match without contributing to score. |
optional |
Contributes to score; constrains only an optional-only boolean unless min_match says otherwise. |
prohibited |
Must not match. |
min_match |
Required number of optional clauses. 0 uses the contextual default. |
With any required or filter clause, optional clauses rank coincident hits
but do not constrain the match set by default. With only optional clauses, at
least one must match. Set min_match to make the optional group an explicit
constraint.
Filters, routing, and domains
Section titled “Filters, routing, and domains”The filter list of a top_docs operation (and of the request shorthand)
holds non-scoring queries ANDed with the main query. Each entry is a bare
expression string, a structured query object, or a routing wrapper that adds
except_ops when sibling operations should not see the filter:
"filter":[ {"match":{"status_s":"active"}}, {"query":"brand_s:acme","except_ops":["brands"]}]The filter still restricts the document results, but the named operations in
TopDocs.ops run without it: a brands facet keeps showing every brand while
the result list is narrowed to one. Names must be distinct, nonempty keys in
that map. Routing is supported by both JSON and protobuf; Fusion filters and
Fusion source filters do not accept except_ops.
An operation in SearchRequest.ops, TopDocs.ops, or a bucket’s ops may
also set a domain:
"brands": { "field_facet": {"field":"brand_s"}, "domain": {"query":"stock_s:yes", "apply_parent_filters":true}}domain.query replaces the incoming document set with that query’s matches
across the operation’s view. Without it, the operation inherits its incoming set.
domain.filter adds local constraints in either case. With a replacement
query, apply_parent_filters: true reapplies the owning list’s filters,
including facet selections, while respecting except_ops. It defaults to
false and requires domain.query; it does not restore the parent’s query or
ancestor matching query. Beneath buckets, a reset preserves every enclosing
bucket identity, including group key equality; see
bucket domain resets. Domain overrides
are not supported directly in Fusion.ops. Selection queries in enclosing
query-facet buckets are re-evaluated in the reset scope, outer to inner.
Phrase
Section titled “Phrase”The common form analyzes one text value:
{"phrase":{"field":"title_t","text":"way of kings","slop":0}}Set exactly one input form:
| Field | Meaning |
|---|---|
text |
One unanalyzed string; the field analyzer produces the phrase terms and positions. |
words |
Unanalyzed word strings, each passed through analysis. |
terms |
Already analyzed string terms. |
terms_bin |
Already analyzed byte terms for typed protobuf callers. |
positions |
Optional explicit positions aligned with terms/terms_bin. |
slop |
Maximum spread of query-adjusted positions. Default 0; must be non-negative. |
Slop is not simply the number of intervening words. An adjacent transposition
costs 2, and multi-valued text fields have a position gap of 100. See
Query language: terms and phrases.
Prefix
Section titled “Prefix”{"prefix":{"field":"title_t","prefix":"mess"}}prefix is an indexed-term prefix, not a wildcard expression. Text fields
apply their multi-term normalization/folding but do not tokenize it; STRING
uses its normalizer if present, and ID uses the bytes verbatim. An empty prefix
matches documents with at least one indexed term for the field.
| Field | Meaning |
|---|---|
field |
Indexed term field. Required. |
prefix |
Literal prefix, including any *, ?, or backslashes. Required. |
case_insensitive |
After normalization, also match other simple Unicode case forms. Default false. |
max_expansions |
Unset or 0: every term with the prefix. Any positive N (no upper bound): in each segment, only the N terms with the highest document frequency (ties keep the lower term). |
A short prefix over a large dictionary can expand to hundreds of thousands of
terms, and an unscored or exactly counted request then reads every one of their
postings lists. max_expansions bounds the selected postings lists, while
selection still scans every matching term. The terms are chosen per segment,
so a term just outside the cut can match in one segment and not in another.
Both capped and complete expansions are subject to any operator-configured limits in
Expansion limits. Selection memory counts toward the
request memory ceiling.
With case_insensitive, the entire prefix is normalized once, then matched
through a case-alternating automaton. TEXT, STRING, and ID are supported, and
queries are constant-scoring. max_expansions selects by document frequency
across the accepted case variants. The expression form is
prefix(err, field=body_w, case_insensitive=true).
Wildcard
Section titled “Wildcard”{"wildcard":{"field":"title_t","pattern":"du*"}}| Field | Meaning |
|---|---|
field |
Indexed term field. Required. |
pattern |
* matches any bytes, ? matches one codepoint, \ escapes the next character. Required. |
case_insensitive |
Literal characters also match their other simple Unicode case forms. Default false. |
The pattern matches an entire indexed term. On TEXT fields, literal characters
fold the way the field folds text, while *, ?, and escapes are syntax and
never fold; STRING fields also normalize literal characters; ID fields use
literals verbatim. With case_insensitive, each literal character, escaped or
not, also matches the lower, upper, and title forms of its folded form, so
err* matches ERROR and Error on a case-preserving field. Wildcard
queries are constant-scoring. The expression form is
wildcard(du*, field=title_t), or
wildcard(du*, field=title_t, case_insensitive=true).
{"regex":{"field":"title_t","pattern":"dune|kings"}}| Field | Meaning |
|---|---|
field |
Indexed term field. Required. |
pattern |
Anchored whole-term regular expression: |, concatenation, groups, repetition, ., and character classes. Required. |
case_insensitive |
Literals and character classes also match their other simple Unicode case forms. Default false. |
The match is anchored to the whole indexed term, so mess does not match
messiah but mess.* does; ^ and $ are literal characters. On TEXT
fields, literal characters fold the way the field folds text; character
classes and ranges are codepoint-exact. STRING fields also normalize literal
characters; ID fields use literals verbatim. With case_insensitive, literals
also match their other simple Unicode case forms, and character classes and
ranges add the case forms of their members before negation: [a-c] matches
B, and [^a] rejects both a and A. Regex queries are constant-scoring.
The expression form is regex(dune|kings, field=title_t). Case expansion counts
toward the pattern complexity budget.
{ "fuzzy": { "field": "author_s", "term": "herbet", "max_edits": 1, "prefix_length": 1, "max_expansions": 0 }}| Field | Meaning |
|---|---|
field |
Indexed term field. Required. |
term |
Term to compare. TEXT normalizes/folds without tokenizing; STRING uses its normalizer if present; ID uses it verbatim. Required. |
max_edits |
Byte-wise Levenshtein distance from 0 to 2. Unset uses 0 for terms of at most 2 bytes, 1 through 5 bytes, then 2. |
prefix_length |
Leading bytes that must match exactly. Unset defaults to 1; explicit 0 disables it. |
max_expansions |
Maximum term expansions, closest first. Unset or 0 uses the default 50; any positive value (no upper bound) pins the cap. |
Terms past the cap are dropped without a response warning. Scoring uses blended BM25 statistics; filter context is constant-scoring, but both use the same expansion set and match set. Simple-query syntax still warns when it clamps an unsupported edit distance before constructing the fuzzy query.
{"range":{"field":"year_i","gte":1960,"lt":1970}}Use at most one lower bound (gte or gt) and one upper bound (lte or
lt). Omit one side for an open range. With no bounds, the range becomes an
exists query.
Numeric and date fields compare column values. Date bounds accept epoch
numbers in the field’s unit (ms or ns), ISO-8601, partial dates, and date math; see
Dates and time zones. String, ID, and text fields range over indexed
terms in byte order with constant scores. Text bounds receive the field’s
normalization/folding but are not tokenized; STRING bounds use its normalizer.
The bare field uses the value binding, including a range with no bounds.
Term ranges are subject to any operator-configured Expansion limits.
Expansion limits
Section titled “Expansion limits”Prefix, wildcard, regex, term-range, fuzzy, and case_insensitive match queries
expand against the field’s term dictionary, so their cost grows with its cardinality. Every
expansion limit is an operator opt-in, off by default. With limits off, a broad
pattern on a high-cardinality field simply runs. Operators exposing a public
endpoint can set these options to bound dictionary work and postings estimates.
When a configured limit is exceeded, the request fails with
RESOURCE_EXHAUSTED, naming the query and limit, never a truncated match set.
A request cannot raise or disable an operator limit. The outcome depends only
on the request’s total, not timing, though work can run slightly past a limit
before the request stops. A filter served from cache scans nothing and counts
nothing.
| Error code | Cause |
|---|---|
too_many_expansions |
A query expands more terms in one segment than the configured cap. A merge can change whether the query passes. |
too_many_terms_examined |
Dictionary scans, matching or not, exceed the request-wide configured visit limit, including fuzzy scans and refills. |
too_many_expansion_postings |
The summed docFreq of selected terms exceeds the configured request-wide estimate limit. This counts estimated postings, not postings decoded; fuzzy’s scored rewrite does not count toward it. |
pattern_prefix_too_short |
An unbounded prefix, wildcard, or regex query has fewer literal leading bytes than the configured minimum. This rule looks only at the normalized pattern, never the index or cache. A type-ahead endpoint using N rejects keystrokes shorter than N. |
A prefix query with max_expansions keeps at most that many terms per segment.
The selected count is subject to any configured too_many_expansions cap, and
its scan counts toward any configured terms-examined budget. The sampling pass
behind an estimated found reuses the search’s expansions, so it adds nothing
to the budget. any_of term
lists are not capped by term count because the request already lists every
term. Finite patterns such as (dune|kings) are exempt from the minimum literal
prefix rule. Case-insensitive matching does not shorten the measured literal.
Match, fuzzy, term ranges, and facet term filters are also exempt from that rule.
See Operations for the server settings.
Range fields
Section titled “Range fields”On a long_range, double_range, or date_range field, the query compares
each stored interval with the query interval. relation picks the test:
relation |
A document matches when its interval |
|---|---|
intersects (default) |
overlaps the query interval |
contains |
covers the whole query interval |
within |
lies inside the query interval |
{"range":{"field":"open_hours","gte":9,"lte":17,"relation":"contains"}}Bounds follow the matching scalar type’s range-query rules. For example, fractional long bounds round inward to integer endpoints; ingest requires integral long endpoints. Malformed bounds are errors even when another bound already makes the query empty. See Range types for strict ingest validation and supported endpoint domains.
A partial date names its whole granule: gte: "2024-06" includes June from
its first millisecond and lte: "2024-06" through its last; gt and lt
exclude the named granule. Luxir uses this rule at ingest too. Elasticsearch
and OpenSearch differ: when they ingest a range field, a partial-date lte
such as "2024-06" does not extend to the end of the month. Ingest uses UTC for dates without an explicit
offset; query dates use the request’s time zone and now follows the scalar
date rules.
An open query side and an open stored end are unbounded within the endpoint
domain: {"gte":50} contains every value from 50 up. For doubles, open ends
are -Infinity and Infinity, and explicit infinities at those ends are
equivalent. NaN is an error. gt: "Infinity" and lt: "-Infinity" match
nothing. Negative zero sorts below positive zero. Long and date open ends
extend to the int64 limits.
A match on a range field, and field:[a TO b] in the
query language, are intersects queries; match with
one value finds intervals containing it. Explicit field literals also work
in simple_query. multi_match accepts explicitly named range fields in
both modes, applies field weights, and skips literals that cannot coerce to
an endpoint, as for numeric fields. Wildcard field selectors do not select
range fields. relation is rejected on other field types unless it is
intersects.
Returned intervals omit open ends. Date endpoints follow the request’s
date_iso, date_ms, or date_ns output mode in ROWS and COLUMNS responses,
with epoch milliseconds as the default. Multi-valued range fields, sort,
facets, collapse, value expressions, and any_of on range fields are not
supported.
Constant score and boost
Section titled “Constant score and boost”Replace every child score while retaining its match set:
{ "constant_score": { "query": {"match":{"status_s":"active"}}, "score": 1.0 }}score defaults to 1.0; explicit 0 is legal.
Multiply child scores without changing matches:
{ "boost": { "query": {"match":{"title_t":"dune"}}, "boost": 2.0 }}boost defaults to 1.0 and must be finite and non-negative. HTTP also
accepts a numeric sibling as input sugar:
{"match":{"title_t":"dune"},"boost":2}. Canonical output uses the wrapper.
Rescore
Section titled “Rescore”Keep the child query’s matches and replace each hit’s score with a value expression:
{ "rescore": { "query": {"match":{"title_t":"dune"}}, "expr": "score * $weight + log1p(popularity_i)", "vars": {"weight": 10} }}| Field | Meaning |
|---|---|
query |
The child query. Its matches are the rescored set. Required. |
expr |
A numeric value expression; score is the child’s score and column names read the document’s values. Required. |
vars |
Scalar values for $name references in expr. |
min_score |
Optional. Documents whose rescored value is below it do not match. |
The expression uses the same value-expression language as sorting (arithmetic,
def, math such as exp and pow, comparisons and ?: conditionals,
random, reducers, and the Elasticsearch-style gauss_decay, exp_decay,
and linear_decay decay functions; see
Searching,
Decay functions, and
Value expressions for the bitwise operators, trigonometry,
date parts, geo functions, hashing, and let) and
must produce a finite value for every matched document. Handle missing values
with def() or exclude them with an exists() clause in the child query.
The expression form is
rescore(title_t:dune, expr=score * log1p(popularity_i)), whose $vars
bind from the surrounding expression’s vars map.
min_score is the counterpart of Elasticsearch’s function_score and
script_score min_score: it compares the expression output, before any
enclosing boost, and removes the document from the match set, so it also
applies when the rescore is a non-scoring filter. In the expression form:
rescore(title_t:dune, expr=log1p(popularity_i), min_score=2). Use
rescore(q, score, min_score=...) for a cut-off on any query’s own score.
Simple query
Section titled “Simple query”simple_query is for raw search-box input and never fails to parse:
{ "simple_query": { "q": "dune | messiah -movie", "fields": ["title_t","description_t"], "operator": "or", "min_match": 1, "allowed_fields": ["title_t","author_s"] }}| Field | Meaning |
|---|---|
q |
Raw user input. |
fields |
Required non-empty fields for unfielded terms; scores add across fields. |
operator |
Default adjacency: or (default) or and. |
min_match |
Minimum top-level optional clauses when the parsed shape can apply it. |
allowed_fields |
Optional allowlist for field:value; empty permits every queryable schema field. |
Unsupported syntax in q degrades to literal terms or produces a search
warning. The Quickstart
shows the intended search-box use.
Expansion fields are resolved through search and deduplicated by physical
identity: author_name and author_name__self from the
author example produce one expansion.
allowed_fields restricts exact resolved search targets; allowing one
representation does not grant access to its siblings.
Multi-match
Section titled “Multi-match”multi_match searches one text across several weighted fields. Choose
combined (the default) to combine term frequencies within analyzer groups,
or per_field to score a match in each field separately:
{ "multi_match": { "text": "dune messiah", "fields": [{"field": "title_t", "weight": 2}, {"field": "description_t"}], "operator": "and" }}| Field | Meaning |
|---|---|
text |
Text to analyze or coerce for each field. |
fields |
Required non-empty list of fields with optional weights. Unset weight is 1; weights must be finite and greater than 0. |
mode |
combined (default) or per_field. |
operator |
or (default) or and; combines terms within each group in combined, or within each field in per_field. Must be unset with phrase. |
min_match |
Non-negative minimum analyzed terms within each group or field. Zero uses operator; a positive value overrides it and is clamped to the analyzed term count. Must be zero with phrase. |
tie |
Combines field or group scores as described below. Finite and in [0, 1]; default 1 in both modes, including with phrase. |
phrase |
Optional object, per_field only. {} requests an exact phrase; {"slop":2} allows phrase slop. |
Fields and weights
Section titled “Fields and weights”JSON accepts field objects as shown above, or "title_t" and "title_t^2"
as shorthand. Writes use the canonical object form. Weights below 1 are
allowed. Fields resolve through their search bindings, like match.
Duplicate physical targets keep the larger weight, and field order does not
affect the query.
In combined mode, TEXT fields with the same expanded analyzer definition
and long_terms policy form a group scored as one field with BM25F, whether
the analyzer is inherited from a common parent or declared inline on each
field.
Group membership is determined by the schema, independently of the query text.
Each group analyzes the text once; a term found in several fields saturates
once within that group. A weight scales its field’s term frequency and
document length, including in a group with just one field. For a term,
frequency is the weighted sum of per-field frequencies, and length is the
weighted sum of per-field lengths, rounded and encoded as a norm. Every
field contributes length even when the term is absent from that field.
Average length is the weighted sum of total term counts divided by the
largest per-field document count; document frequency is the largest
per-field document frequency. This is a BM25F weight, not a score multiplier;
the scoring follows Lucene’s CombinedFieldQuery.
STRING, ID, numeric, and date fields each form their own group with match
semantics and a weight that multiplies the field’s score. STRING/ID fields
match the whole text as one value. Numeric/date fields coerce it to a value
and match through their columns.
In per_field mode, each field runs its own match query and its weight
multiplies that field’s score. This mode accepts the same field types as
match. Use per_field to multiply individual field scores, or
wrap the whole query in boost to multiply its
final score.
A document matches when any group (combined) or field (per_field)
matches. Within a TEXT group, different terms may occur in different fields.
operator: "and" requires every term somewhere within one matching group;
it does not require every group to match. In per_field, AND requires every
term in the same field. min_match also applies within each group or field.
A group producing no terms contributes nothing.
In both modes, including with phrase, a field whose text cannot be coerced
to its value type is silently skipped. For example, "dune" over title_t
and year_i searches only the title; "1965" can also match the year.
Unknown fields, unsupported field types, and other errors still fail the
request. Single-field match remains strict about coercion errors. If no
field contributes a clause, the query matches nothing. Changing tie or
using the query as an unscored filter does not change its match set.
Combining scores
Section titled “Combining scores”tie combines the scores of matching groups in combined mode, or matching
fields in per_field mode. With best the largest matching score and sum
the sum of matching scores:
score = best + tie * (sum - best)The default, tie: 1, adds all scores. tie: 0 keeps only the best score;
values between them retain a fraction of the other scores. For example, to
score the best field, with a weight of 2 on the title:
{ "multi_match": { "text": "dune", "fields": ["title_t^2", "description_t"], "mode": "per_field", "tie": 0 }}For applications using Elasticsearch’s multi_match vocabulary:
| Elasticsearch name | Luxir options |
|---|---|
best_fields |
mode: per_field, tie: 0 |
most_fields |
mode: per_field (default tie: 1) |
cross_fields (approximate) |
mode: combined, tie: 0 |
phrase |
mode: per_field, with a phrase object |
These are combinations of options, not mode names. Luxir defaults to
tie: 1 for both modes, including with phrase; set tie: 0 for the best
phrase field.
The expression form accepts field weights and enum arguments:
multi_match(dune messiah, fields=[title_t^2, description_t], operator=and)multi_match(dune, fields=[title_t^2, description_t], mode=per_field, tie=0)Phrase options
Section titled “Phrase options”Set phrase in per_field mode to run a phrase per TEXT field. An empty
object requests an exact phrase; slop defaults to 0 and must be
non-negative. Slop measures the spread of query-adjusted positions, as for
phrase:
{ "multi_match": { "text": "dune messiah", "fields": ["title_t^2", "description_t"], "mode": "per_field", "phrase": {"slop": 2} }}Every selected TEXT field must have indexed positions; selecting one
without positions is an error. STRING/ID fields still match the whole text
as one value, and numeric/date fields still use match coercion. Field weights
multiply these scores, and tie combines them.
With phrase present, combined mode, any explicit operator (including
or), or a positive min_match is an error. The expression forms are:
multi_match(dune messiah, fields=[title_t^2, description_t], mode=per_field, phrase={})multi_match(dune messiah, fields=[title_t^2, description_t], mode=per_field, phrase={slop: 2})Field patterns
Section titled “Field patterns”A field name containing * expands to indexed TEXT, STRING, and ID search
targets. * matches zero or more characters; numeric/date fields must be
listed explicitly. A pattern’s weight applies to every field it selects:
{"multi_match":{"text":"dune","fields":["*_t^0.5","title_t^2"]}}Patterns without __ select logical roots through their search bindings;
patterns containing __ select variants. The catalog includes concrete
schema declarations even when absent from the index. Dynamic roots come
from reader metadata, along with their schema-defined variants even when
a variant is absent. Templates do not invent unknown dynamic roots.
Patterns exclude engine names and the __self alias. A pattern matching
nothing adds no field.
A field list containing a pattern may resolve to at most 64 distinct
physical targets, including explicitly listed fields. Overlapping patterns
and aliases count once and keep the larger weight. Exceeding the limit is
an error. The same selectors work in the expression form:
multi_match(dune, fields=["*_t^0.5", title_t^2])Disjunction max
Section titled “Disjunction max”dis_max matches a document when any of its queries matches. It combines
matching query scores with the same formula as multi_match:
best + tie * (sum - best). Its default tie is 0, keeping only the
best query’s score:
{ "dis_max": { "queries": [ {"match":{"title_t":"dune"}}, {"match":{"description_t":"dune"}} ], "tie": 0.3 }}| Field | Meaning |
|---|---|
queries |
Required non-empty list of queries. |
tie |
Finite and in [0, 1], default 0. 0 keeps the best score; 1 adds all scores like a boolean disjunction. |
Only matching queries contribute. Duplicate queries are kept as separate
scoring contributions: repeating a query leaves the best score unchanged at
tie: 0, but contributes again to the sum at positive tie. A single query
scores as itself. tie: 1 is equivalent to a boolean disjunction.
In a filter, dis_max matches the same documents as a boolean disjunction of
its queries and shares that disjunction’s filter cache entry. The expression
form takes a list of query sub-expressions:
dis_max(queries=[title_t:dune, description_t:dune], tie=0.3)Expression
Section titled “Expression”The expr arm holds a query-language string and its variables:
{ "expr": { "q": "title_t:$title AND year_i:>=$year", "vars": {"title":"Dune","year":1965} }}A bare JSON string is sugar for expr.q. Variables are substituted as values,
not parsed as query syntax. See Query language for the full
grammar and the function-call subset.
Vector and geo
Section titled “Vector and geo”Vector and geographic queries use the same Query node and are documented
in their own guides:
- A child-field
knncounts rows of the view where it is written; see Chunks and vectors. knncoversfield,query,k,refine_candidates,exact,similarity, and the per-engineivfobject (nprobe,min_scan_fraction).geo_box,geo_distance, andgeo_polygoncover coordinate order, inclusive boundaries, dateline crossing, distance units, and unions of polygons with holes.
Limits
Section titled “Limits”knn,geo_box,geo_distance, andgeo_polygonare structured-only: expression functions cannot currently represent vector or coordinate-list arguments, so use the objects shown in the vector and geo guides.- New structured arms are not automatically callable from the query language until their expression behavior is declared.
except_opsrouting is not accepted on Fusion filters or Fusion source filters, anddomainoverrides are not supported directly inFusion.opsor beneath facet buckets.multi_matchlists containing field patterns are limited to64distinct physical targets after resolving search bindings and deduplicating, including explicitly listed fields. Patterns select indexed TEXT/STRING/ID targets.multi_match.phraserequiresper_fieldmode and indexed positions on TEXT fields; it cannot be combined with an explicitoperatoror a positivemin_match.- Fuzzy expansion truncation at
max_expansionsis not reported in the response. - Operators can opt in to request-wide limits on multi-term and fuzzy dictionary work; see Expansion limits.
Nested row queries and domains
Section titled “Nested row queries and domains”A single-field leaf naming a descendant field implicitly uses to_parent with
score max; each leaf joins independently. Wrap a Boolean child in
{"to_parent":{"path":"items","query":{...}}} for a same-item query.
Its optional score is max (default), min, sum, avg or none
(contributes zero), and optional min_children (default 1) and
max_children (default unbounded) bound the number of matching children;
see Scoring. An exists query on a nested
path joins all rows of that path. Query strings additionally support nested
field groups, such as items:(color:red AND size:L).
Operations move between views through domain.to: relative dotted descent,
.. or ../.. ascent, and / for root documents. Mixed upward/downward
paths are reserved. Non-query field consumers must run in their field’s own
view. See Nested documents for examples and the precise
query/consumer distinction.