Skip to content
Development documentation for unreleased code on main. Behavior can change before a release. Latest release docs

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.

POST /collections/books/_search
{"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.

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.

{"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.

any_of matches any listed value in the value representation. With the authors collection from Documents and values:

POST /collections/authors/_search
{
"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": {
"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.

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.

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":{"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":{"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.

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.

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.

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.

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 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 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.

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.

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)

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})

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])

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)

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 geographic queries use the same Query node and are documented in their own guides:

  • A child-field knn counts rows of the view where it is written; see Chunks and vectors.
  • knn covers field, query, k, refine_candidates, exact, similarity, and the per-engine ivf object (nprobe, min_scan_fraction).
  • geo_box, geo_distance, and geo_polygon cover coordinate order, inclusive boundaries, dateline crossing, distance units, and unions of polygons with holes.
  • knn, geo_box, geo_distance, and geo_polygon are 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_ops routing is not accepted on Fusion filters or Fusion source filters, and domain overrides are not supported directly in Fusion.ops or beneath facet buckets.
  • multi_match lists containing field patterns are limited to 64 distinct physical targets after resolving search bindings and deduplicating, including explicitly listed fields. Patterns select indexed TEXT/STRING/ID targets.
  • multi_match.phrase requires per_field mode and indexed positions on TEXT fields; it cannot be combined with an explicit operator or a positive min_match.
  • Fuzzy expansion truncation at max_expansions is not reported in the response.
  • Operators can opt in to request-wide limits on multi-term and fuzzy dictionary work; see Expansion limits.

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.