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

Faceting and metricsdev

Faceted search groups matching documents into buckets and returns information about each bucket. A book search might group matches by category, price range, or publication year. Each bucket has a count; you can also compute metrics such as average price, group its documents into sub-buckets, or retrieve its top matching documents. Buckets can overlap: a book can belong to both science-fiction and classics.

In a search UI, these summaries become choices such as “Science fiction (31)” or “Under $20 (18)”. Users can see how results are distributed and select values to narrow their search.

One request returns the top documents for a page along with the facets and metrics for it. Put facets and metrics in the sub operations ops of a query and they see every document the query and its filters match, not just the hits returned by limit. The ranked documents, the facet counts, and the total come back in one round trip, over one consistent view of the index. Counts are exact by default. A document contributes once to each bucket it matches, including when an array repeats a value or several values fall in the same range bucket. Bucket metrics see each matching document once; metrics over its field values still see all values stored by the field’s set or array mode.

For an interactive facet sidebar, start with selected: put the user’s choices on each facet and Luxir builds the filters and handles multi-select counts automatically.

POST /collections/books/_search
{
"query": "title_t:dune",
"filter": ["stock_i:>0"],
"limit": 10,
"count_limit": -1,
"fields": ["id","title_t"],
"ops": {
"categories": {
"field_facet": {"field":"category_s","limit":10,"missing":true}
},
"average_price": "avg(price_f)"
}
}
{
"found": 42,
"docs": [
{
"id": "b1",
"title_t": "Dune"
}
],
"ops": {
"categories": {
"buckets": [
{
"val": "science-fiction",
"count": 31
},
{
"val": "classic",
"count": 9
}
],
"missing": 2
},
"average_price": 11.72
}
}

Every entry in ops is a named operation, and operations nest. A facet’s own ops run once per bucket, so one category facet can return the average price, a publisher breakdown, and the two best documents of every category. The whole tree executes as part of the original request rather than as a follow-up query per bucket.

Bucket operation names cannot be val, count, rank, singleton or missing; these names identify bucket and group metadata. The same children can run per returned group through collapse.ops. Facets there count the group’s matching documents by default.

The operation kinds on this page:

Operation Groups by
field_facet Each distinct value of a field.
range_facet Fixed-width or calendar buckets over a numeric or date field.
query_facet Named buckets you define with arbitrary queries.
Expression metric ("avg(price_f)") Nothing; one scalar such as an average, distinct count, or percentile.
top_docs / fusion Nothing; a ranked document list per bucket.

Use selected to send the current choices along with each facet. Luxir turns them into filters for the results and excludes each facet’s own selection when counting that facet’s buckets, so the alternatives stay visible.

Here the user has checked two categories and one format:

POST /collections/books/_search
{
"query": {"all":true},
"filter": ["stock_i:>0"],
"limit": 10,
"count_limit": -1,
"fields": ["id","title_t"],
"ops": {
"categories": {
"field_facet": {
"field": "category_s",
"limit": 10,
"selected": ["science-fiction","fantasy"]
}
},
"formats": {
"field_facet": {
"field": "format_s",
"limit": 10,
"selected": ["paperback"]
}
},
"average_price": "avg(price_f)"
}
}

The default selection_mode: "any" combines choices with OR within a facet and AND across facets. Luxir applies the query and the stock filter everywhere, then handles the selections for each part of the response:

Result Selections applied
docs, found, and average_price Science-fiction or fantasy, and paperback.
categories buckets Paperback; count all categories so the user can choose more.
formats buckets Science-fiction or fantasy; count all formats so the user can choose more.

Each facet ignores only its own selection when counting its buckets. Update its selected array as the user checks or unchecks values; omit it or send [] to clear that facet’s selection. Selected buckets stay in the response even when outside limit, so the UI can keep showing the checked choices.

The same API works for field, range, and query facets directly under the query’s ops. See Multi-select navigation for selection values, normalization, and the stricter selection_mode: "all".

Under a collapsed list, field, range, and query facets count distinct groups by default. A product contributes once to a color bucket if a matching variant in that facet’s document domain has that color. The count uses the collapse key and its missing policy, including tuple keys.

{
"collapse": "product_id_s",
"limit": 10,
"ops": {
"colors": {"field_facet": {"field": "color_s", "limit": 20}},
"variant_colors": {
"field_facet": {"field": "color_s", "count_unit": "docs"}
},
"average_price": "avg(price_i)"
}
}

count_unit: "docs" counts documents. count_unit: "groups" requires an enclosing collapsed list and uses the nearest one’s key and missing policy. Nested facets inherit their parent’s measure, including an explicit docs override. Each nested facet still sees only the documents in its parent bucket. An uncollapsed child top_docs remains a document list; its facets inherit the counting measure. A child list with its own collapse establishes a new key and default measure. Entering collapse.ops resets the default to docs; an explicit count_unit: "groups" there still uses the nearest enclosing collapse and counts one where that group has members.

The measure governs bucket counts, their default order, mincount, and missing. The missing bucket counts a group when any document in the facet’s domain lacks the facet value. That group can also occur in named buckets, so bucket counts need not sum to found. Selected buckets retain their exact counts, including zero, even below mincount or outside the ordinary page.

Selections and except_ops still filter individual documents. With a size=M filter, a color bucket counts only variants of size M. A product with red/S and blue/M contributes to blue, not red. Metrics such as avg(price_i) fold the bucket’s documents and remain document-weighted.

Use count_distinct to count an independent key, including outside collapse:

{
"limit": 0,
"ops": {
"authors": {
"field_facet": {
"field": "category_s",
"count_distinct": {"field": ["publisher_s", "author_s"], "missing": "drop"}
}
}
}
}

The key specification accepts the same fields and missing policies as collapse; a field-name string is shorthand. An explicit count_unit and count_distinct must describe the same measure. docs conflicts with any distinct key. Counts are exact across segments, including scattered updates and deletes. Keys retain their exact values, including numeric extrema and every tuple null pattern. Missing keys under expand each form their own group. Group counting adds no work during indexing or reader reopen.

A group can contribute to many buckets, and the engine must recognize it across segments and parallel workers. Memory grows with the number of matching groups, facet values, and distinct combinations, rather than only the number of returned buckets. Broad multi-valued and high-cardinality facets can cost substantially more than document counting. Tuple keys can also add work when their component ranges are large.

Distinct counting uses the request memory budget. Exceeding the budget fails the request; counts never become estimates or document counts. Use count_unit: "docs" when document counts are the intended measure.

Distinct counting supports STRING/ID and numeric/boolean/date field facets, numeric/date range facets, and query facets, including overlapping query buckets and nested operations. TEXT field facets and metric sorts with distinct counts remain unsupported. FLOAT/DOUBLE can be facet fields, but cannot be distinct key fields; the key types are the same as for collapse.

A field_facet groups by distinct field value. For example, count books in each category:

POST /collections/books/_search
{
"query": {"all": true},
"limit": 0,
"ops": {
"categories": {
"field_facet": {
"field": "category_s",
"limit": 10,
"missing": true
}
}
}
}

The response contains a bucket for each category and its document count:

{
"docs": [],
"ops": {
"categories": {
"buckets": [
{
"val": "science-fiction",
"count": 31
},
{
"val": "classic",
"count": 9
}
],
"missing": 2
}
}
}

Here, 31 books have category science-fiction, 9 have category classic, and 2 have no category. The request’s limit: 0 omits individual books; the facet’s limit: 10 returns up to ten categories.

Field Meaning
field Field to group. Required.
limit Maximum returned buckets. Default 5; -1 returns all.
mincount Drop buckets below this count.
missing Also return the count of documents with no value in the field.
sort Sort buckets by one of the facet’s metric sub-operations: a one-element list such as ["name desc"] or ["name asc"]. Default: count descending.
ops Per-bucket sub-facets, metrics, or top_docs / fusion lists.
selected Values that refine the result set and stay visible as buckets. See Multi-select navigation.
selection_mode any (default) or all: match any selected value, or require every one.
term_filter String and ID fields only. Restricts which terms can become buckets; counts stay exact. See Filtering bucket terms.

String and ID facets return buckets in count-descending order, with bucket value ascending as a deterministic tie break. Default bucket counts are document counts in either multi-valued mode. mincount: 0 includes values that exist in the collection but have zero matches in the current result set, which keeps a sidebar stable while the user narrows a search.

Integer, floating-point, boolean, and date fields facet on each distinct column value. Boolean bucket ids are JSON false and true, also accepted in selected; boolean fields do not support range facets. FLOAT/DOUBLE keep -0.0 and 0.0 in separate buckets, matching exact query equality; all NaNs share one bucket. HTTP JSON renders NaN and infinities as null, so those bucket labels cannot be sent back as selections.

A numeric, boolean, or date field declared with index: "match" also has a term dictionary, and its field facets count from it wherever that reads less than the column: an unfiltered facet takes each value’s document count from the dictionary without visiting documents, a facet over most of the index subtracts the documents outside the result set, and a selective one can intersect each value’s postings with the result set. Bucket domains for sub-operations come from the same postings when they read less than the column. Each segment chooses by its number of distinct values against the documents to count, so a field with a distinct value per document keeps the column scan, and segments written before the field had a dictionary keep it too. Results do not depend on the choice. Declare match on low- and medium-cardinality fields that are faceted (ports, status codes, enumerated ids); the dictionary adds index size and indexing work, and a field has one index mode, so it cannot also have the range points index.

Text fields facet on analyzed terms, not on the stored text: a facet on body_t returns indexed words, while a facet on category_s returns whole category values. Text facets also accept mincount: 0, while numeric, boolean, and date field facets require a positive value when set. Use a range facet when numbers should be bucketed rather than enumerated.

A string facet needs indexed terms and a column. Facets return the term as stored. For fields with multiple representations, see Field variants.

term_filter limits which terms of a string or ID field can become buckets, for example an autocomplete over category names or a facet over the values a caller is allowed to see. It is not a query filter: every term is still counted in the facet’s domain, so the counts of the remaining buckets are exactly what they would be without the filter, and limit applies to the filtered terms (limit: 1 with "prefix": "b" returns the best b term, not nothing because an a term ranked first).

{
"field": "category_s",
"limit": 10,
"term_filter": {"prefix": "sci", "exclude": ["science-fiction-misc"]}
}
Field Meaning
prefix Keep terms starting with this prefix.
regex Keep terms matching this regular expression in full, with regex query syntax.
exclude_regex Drop terms matching this regular expression in full.
include Keep only these exact terms. An empty list is unset.
exclude Drop these exact terms.
partition, num_partitions Keep terms whose stable hash modulo num_partitions equals partition. Requests for partitions 0 to num_partitions - 1 together return every term exactly once, so a client can page through a very large term set. The hash is 64-bit FNV-1a over the indexed term bytes.

Every condition that is set must hold. Literals are matched the way the field indexes terms: prefix, include, and exclude are normalized like the same values in a prefix or any_of query, regex and exclude_regex are compiled like a regex query (field folding per character), and ID fields use them verbatim. A regex whose literal start is longer than a field keeps of a long value matches every term with the kept prefix, as the regex query does. Otherwise both regexes test a long value’s indexed bytes (an exclude_regex never widens, since that would drop terms it does not match), and the response carries a fitted_terms warning when that can happen.

A prefix, the literal start of a regex, and the include and exclude lists resolve to ranges of terms once per request, and bucket selection walks only those ranges. The rest of a regex, exclude_regex, and partitions read each candidate term, so they cost more on a high-cardinality field.

The filter changes only the ordinary buckets:

  • missing still counts every document in the domain without a value.
  • mincount: 0 pads with zero-count terms that pass the filter.
  • selected buckets are always returned, whether or not they pass the filter.
  • Sub-operations and nested facets run on the buckets that pass.

term_filter is rejected on numeric, boolean, date, and text fields.

An expression metric folds document values over its incoming documents. The shortest form is a bare expression string in an operation position:

"average_price": "avg(price_f)"

The aggregates are avg, sum, min, max, cardinality, percentile, and percentile_rank. Their value arguments use the same expression language as sort expressions: arithmetic, parentheses, def, unary math, and per-document array reducers. sum(count(field)) counts values, like Elasticsearch value_count, for numeric, boolean, date, STRING, ID and GEO_POINT fields alike. A composite metric is a single expression:

"weighted_price": "sum(price_f * qty_i) / sum(qty_i)"

Bucket expressions also support comparisons, &&, ||, and if/?: with the same conditional semantics as document expressions. For example, sum(price_f) > 0 ? log(sum(price_f)) : 0 avoids a math-domain failure for a non-positive sum.

Distinct counts, percentiles, and the percentage of prices at or below a bound are scalar metrics too:

POST /collections/books/_search
{
"limit": 0,
"ops": {
"publishers": "cardinality(publisher_s)",
"p95_price": "percentile(price_f, 95)",
"affordable": "percentile_rank(price_f, 20)"
}
}
Aggregate Result Constant arguments
cardinality(x [, threshold]) int64 distinct count. threshold defaults to 3000; an integer in [0, 40000].
percentile(x, p [, compression]) Double p-th percentile. p in [0, 100]; compression defaults to 100, in [20, 1000].
percentile_rank(x, v) Exact double percentage of values <= v. v is the bound.

Trailing arguments must be finite numeric constants or scalar $vars.

The explicit forms are {"expr_op":"avg(price_f)"} and {"expr_op":{"expr":"avg(price_f)","vars":{...}}}; the object form takes a vars map for scalar $name values.

Directly under the query’s ops (or at the root of a full-form request), a metric is one scalar over the whole match set. Nested under a facet, it is evaluated independently for each bucket and returned beside the bucket:

"categories": {
"field_facet": {
"field": "category_s",
"limit": 10,
"ops": {
"average_price": "avg(price_f)",
"lowest_price": "min(price_f)"
}
}
}
{
"buckets": [
{
"val": "paperback",
"count": 20,
"average_price": 11.25,
"lowest_price": 5.99
},
{
"val": "hardcover",
"count": 8,
"average_price": 24.50,
"lowest_price": 15.0
}
]
}

Sort a field facet by one of its metrics:

{
"field_facet": {
"field": "category_s",
"limit": 5,
"ops": {"average_price": "avg(price_f)"},
"sort": ["average_price desc"]
}
}

Field facet sort names a sort-capable metric operation of that facet; asc and desc are both supported. percentile_rank supports metric sorting. A bucket whose metric is missing or failed sorts last either way. See Limits for restrictions.

The typing rules:

  • cardinality accepts numeric, boolean, or date expressions and indexed STRING/ID columns, and flattens multi-valued inputs.
  • Other aggregates require one scalar per document. Reduce multi-valued columns first: avg(avg(prices_fs)) averages each document’s prices, then averages those across the bucket.
  • Missing document values are skipped. def(value, 0) counts a missing value as 0 in a sum or a denominator. cardinality, percentile, and percentile_rank also skip NaN and infinity.
  • Integer sum, min, and max return int64 values and accumulate exactly; avg and floating-point sum, min, and max return a double. With no contributing values, cardinality returns 0 and other aggregates return null. Data-dependent overflow or a non-finite result returns null with a response warning.
  • avg, min, max, and percentile of a date keep their DATE nature and unit (ms or ns). Date averages and percentiles are doubles in that unit and can contain fractional ticks or lose precision for large ns values. Date output follows the metric operation’s effective date mode; ISO output floors these doubles to the field’s tick. An invalid ISO date is a request error. See date modes. cardinality and percentile_rank return plain numbers. sum requires numeric values. Multiplication, division, unary minus, and unary math turn a date into a plain number.
  • Decimal avg and percentile keep their scale, like min, max, and sum. Their results are doubles, in raw units under decimal_scaled. percentile_rank uses a value-unit bound and returns a percentage in either mode.
  • For a bare FLOAT column, percentile_rank rounds its bound to FLOAT, matching range queries. Expression inputs use a double bound.

cardinality is exact up to threshold distinct values, then switches to a HyperLogLog estimate with a standard error of about 1.6% at the default threshold (0.4% at 40000). For indexed STRING/ID inputs, the result may be exact beyond the threshold. A larger threshold extends the sketch’s exact phase and uses more memory; 0 estimates from the first value.

percentile is exact for fewer than 5 x compression values (500 by default), interpolating linearly between adjacent ranks. Larger inputs use a t-digest: higher compression uses more memory for finer rank estimates, with no strict error bound. The minimum and maximum (p = 0 and 100) are exact. Results are deterministic for a fixed set of segments; segment merges can change estimates.

Each bucket has its own state. Calls with the same function, input, and compression or threshold share one sketch within an expression, and sibling metrics that use exactly the same sketches share them too: p50, p95, and p99 metrics on one field build a single t-digest. Sketch allocations count against the request memory limit. percentile_rank uses two counters and is exact regardless of the number of values.

Facets can contain other facets. Each sub-facet sees only the documents in its parent bucket:

"category": {
"field_facet": {
"field": "category_s",
"limit": 10,
"ops": {
"publisher": {
"field_facet": {"field":"publisher_s","limit":5}
}
}
}
}
{
"buckets": [
{
"val": "science-fiction",
"count": 31,
"publisher": {
"buckets": [
{
"val": "ace",
"count": 12
},
{
"val": "orb",
"count": 7
}
]
}
}
]
}

Nesting is not limited to one level, and metrics sit beside sub-facets in the same ops map.

A top_docs (or fusion) operation under a facet returns a ranked document list for every bucket: the best few products per category, the latest post per author. It is an ordinary operation with its own query, filter, sort, limit, fields, and count_limit, applied to that bucket’s documents:

"category": {
"field_facet": {
"field": "category_s",
"limit": 10,
"ops": {
"best": {
"top_docs": {
"query": "title_t:dune",
"limit": 2,
"fields": ["id","title_t"],
"count_limit": -1
}
}
}
}
}
{
"buckets": [
{
"val": "science-fiction",
"count": 31,
"best": {
"found": 31,
"docs": [
{
"id": "b1",
"title_t": "Dune"
},
{
"id": "b7",
"title_t": "Dune Messiah"
}
]
}
},
{
"val": "classic",
"count": 18,
"best": {
"found": 18,
"docs": [
{
"id": "b3",
"title_t": "Dune"
},
{
"id": "b9",
"title_t": "Children of Dune"
}
]
}
}
]
}

A top_docs without a query selects every document in the bucket, and without a sort that list is in index order. A text query’s scores do not depend on the bucket, so repeating the outer query ranks each bucket the way the main result list is ranked.

A bucket’s top_docs can use its own collapse, under field, range, or query facets. For example, return the cheapest matching variant of each product within each category:

{
"limit": 0,
"ops": {
"categories": {
"field_facet": {
"field": "category_s",
"ops": {
"products": {
"top_docs": {"collapse": "product_s", "sort": "price_i asc", "limit": 3}
}
}
}
}
}
}

The child list collapses only its bucket’s documents. Its facets default to groups under its own key, and explicit count_unit: "groups" uses that nearest collapse. A descendant domain reset keeps the enclosing bucket identities while replacing the matching query, as for other bucket children.

Per-bucket lists work under field, range, and query facets. A per-bucket top_docs may carry its own ops, which see every document in the bucket that its query and filters match, regardless of its limit; a per-bucket fusion runs its ops over its fused candidate set. Two differences from a top-level list: it is never streamed in batches (batch_size is ignored and every row arrives in the final response), and a document_format left at the default follows the transport default rather than the enclosing operation’s. Each bucket is ranked independently, which costs one pass over the bucket’s documents per bucket.

A range_facet builds ordered, half-open [start,end) buckets over an int, float, double, or date field:

"price_ranges": {
"range_facet": {
"field": "price_i",
"start": 0,
"end": 30,
"gap": 10,
"mincount": 0,
"missing": true
}
}
{
"buckets": [
{
"val": [0, 10],
"count": 4
},
{
"val": [10, 20],
"count": 9
},
{
"val": [20, 30],
"count": 0
}
],
"missing": 2
}
Field Meaning
field Numeric or date field. Required; its value binding must be numeric or date.
start, end Bounds of the bucketed range. Required unless bounds is data, where they only widen it.
bounds explicit (default) or data; see Data-derived bounds.
origin With bounds: data and a fixed gap, the grid phase. Default 0; wall-clock field units (ms or ns) for DATE. Rejected with calendar_gap.
gap Fixed bucket width (field units for dates). Exactly one of gap or calendar_gap is required.
calendar_gap {"n": 1, "unit": "month"} for civil buckets over dates; see Date histograms.
mincount 0 (default) keeps every bucket in order, zero counts included; a positive value filters after counting.
missing Also return the count of documents with no value.
ops Per-bucket metrics, nested facets, or top_docs.
selected Lower fences of buckets that refine the result set. EXPLICIT only. See Multi-select navigation.
time_zone DATE time zone for offset-less bounds and fixed or calendar stepping; empty inherits the request’s.

Buckets return in lower-bound order; the default mincount: 0 includes zero counts. With EXPLICIT bounds, the first fence is start and the last is end, clipping the final bucket if needed. NaN and infinity fall outside every floating-point bucket, including under DATA, and never make DATA fail. The gap must advance the field’s numeric representation at that magnitude. The generated span may contain at most 100,000 buckets, including empty interior buckets and widening. A range facet with sub-operations may return at most 1,024 buckets, checked after mincount filtering (and selected-bucket retention) for both EXPLICIT and DATA. Sub-operations have the same semantics as under a string bucket, so an empty range bucket yields null metrics.

For numeric and date fields declared with index: "range", a points index can answer a whole-index range facet from indexed points instead of walking the column when each document has at most one stored value. Other columns walk document runs to count each document once per bucket. The result is the same either way; only the cost differs.

When each document has at most one value, the column walk reads min/max bounds per block and per 512 values. A run of values whose bounds fall inside one bucket is counted without decoding, so histograms over time-ordered data cost about one step per run rather than one per value. This holds for explicit and data bounds alike. Filtered facets, sub-operation facets and segments with deleted documents get this when the field has one stored value in every document of the segment; other shapes, and distinct counts, walk documents.

Set "bounds": "data" to derive the histogram’s extent from values in the facet’s own incoming documents, rather than specifying both bounds:

"per_hour": {
"range_facet": {
"field": "when_dt",
"bounds": "data",
"gap": 3600000,
"time_zone": "America/New_York"
}
}

The extent runs from the cell containing the smallest matching finite value through the cell containing the largest. Queries, filters and deletions affect that extent. Occupancy uses raw field values, independently of the count measure: a value whose distinct key is dropped still occupies its cell even if the cell’s count is zero. mincount filters the resulting buckets afterward. Under a parent bucket, each histogram instance spans its own incoming values, as with an Elasticsearch histogram under a terms bucket. Parent buckets can therefore return different spans on the same grid. A child domain reset uses that child’s incoming documents.

Optional start and exclusive end only widen the extent; they do not exclude values or clip cells. The span includes the cell containing start and all cells intersecting the requested range before end, like extended bounds. Without values, no buckets are returned unless both start and end supply a span; one widening bound alone cannot define an empty histogram.

The grid is independent of the matching minimum:

  • For INT, DECIMAL, FLOAT and DOUBLE fixed gaps, fences are origin + k * gap for a global integer k; default origin is 0. Floating fences use the field’s encoded representation, so rounding does not shift the grid with the query. Decimal gaps and origins must be exact at the field’s scale; decimal_scaled interprets them in raw integer units.
  • For DATE fixed gaps, origin is a wall-clock phase in the facet zone, expressed in integer field units (ms or ns). For an ms field, gap: 86400000 and origin: 21600000 start days at 06:00 local, including DST days. Luxir applies this phase before resolving local times. Elasticsearch’s offset translates the rounded grid in UTC, so nonzero phases can differ near DST changes; origin is not an exact synonym for that offset.
  • DATA calendar gaps align to civil unit starts. For n > 1, the phase is anchored at the 1970 civil epoch: days from 1970-01-01, months and quarters from January 1970, and years from 1970. ISO weeks anchor at Monday 1969-12-29. Thus two-month buckets cover Jan-Feb, Mar-Apr, and so on, regardless of the query. A civil day begins at its first midnight occurrence; if midnight is skipped, it begins at the first valid instant of that day. Calendar gaps reject origin.

selected is not supported with DATA. The 100,000-bucket cap applies to each instance’s actual span, including empty interior cells and widening, rather than to the field-wide range or the number of nonempty buckets. Exceeding it fails the request with use a larger gap. The 1,024 returned-bucket sub-operation cap applies after mincount filtering.

Date bounds accept epoch numbers in the field’s unit, ISO-8601 text, and both Solr and Elasticsearch/OpenSearch date-math syntax. Use calendar_gap when buckets should follow civil days, weeks, months, quarters, or years:

"by_month": {
"range_facet": {
"field": "published_dt",
"start": "NOW/MONTH-12MONTHS",
"end": "NOW/MONTH+1MONTH",
"calendar_gap": {"n":1,"unit":"month"},
"time_zone": "America/New_York"
}
}

The facet time_zone controls offset-less bounds and fixed or calendar stepping. Empty inherits the request time zone; UTC explicitly overrides it. IANA zone names and fixed offsets are accepted. Bucket IDs are fence pairs, rendered in the facet operation’s effective date mode: native numeric units, normalized ms/ns, or UTC ISO strings. Field-facet values use the same modes. The facet time zone never changes the output zone.

Bucket identities and counts remain native. Under date_ms, ns buckets narrower than one ms can have duplicate displayed bounds; their displayed IDs then no longer identify a bucket for selection. For buckets whose fences are exact ms ticks (for example, a UTC histogram with a one-ms gap), the returned lower bound selects the same bucket in a date_ms request. selected takes the lower bound, rather than the whole fence pair.

Fixed gaps use the field’s unit by default, including one-ns gaps on an ns field. Numeric start, end, gap, origin, and selected use the date mode’s literal unit (date_ms or date_ns overrides the field unit). DATA works for both units and shares its fence identities with EXPLICIT. An ns exclusive end can be INT64_MAX, which is reserved and never stored.

Fixed gaps step on the local clock in both EXPLICIT and DATA modes. Every occurrence of a repeated lattice time is a fence, so an hourly histogram has two separate 01:00 buckets at a fall-back. A nonexistent lattice time maps to the DST transition instant, with duplicate fences removed. EXPLICIT takes its phase from the local time of start, then clips its last bucket to end. This changes EXPLICIT fixed-gap results across DST when local stepping adds or moves fences relative to elapsed-time stepping; buckets follow the local clock. UTC, fixed offsets and spans without a transition retain elapsed-time results.

EXPLICIT calendar fences are derived from the original start for every n, rather than by repeatedly adding to the previous fence, so a sequence starting on January 31 produces February 28 or 29 and then March 31 instead of drifting. Days across a daylight-saving change are 23 or 25 physical hours. DATA weeks begin on Monday; EXPLICIT weeks step from start. An ambiguous EXPLICIT calendar fence prefers the UTC offset of start when that offset is available. DATA calendar alignment is described above. When a zone change removes a whole nominal bucket, Luxir drops the zero-width bucket and returns a calendar_bucket_skipped warning. Dates and time zones has the date-math and civil-time contract.

For a fixed UTC epoch-day number on an ms field in the value-expression language, use floor(when_dt / 86400000); use a calendar gap when day bucketing must follow a civil time zone.

A query_facet names an ordered set of buckets, each defined by a query. In JSON, buckets is an object: each key is the bucket name and each value is a query, as an expression string or a structured object:

"price_tiers": {
"query_facet": {
"buckets": {
"budget": "price_i:[* TO 100]",
"mid": {"range":{"field":"price_i","gte":100,"lt":1000}},
"nearby": {"match":{"field":"region_s","val":"local"}}
},
"ops": {
"average_price": "avg(price_i)"
}
}
}
{
"buckets": [
{
"val": "budget",
"count": 12,
"average_price": 72.5
},
{
"val": "mid",
"count": 31,
"average_price": 340.0
},
{
"val": "nearby",
"count": 0,
"average_price": null
}
]
}

The response keeps request order and retains every requested bucket, including zero counts. Any query kind can define a bucket: boolean, range, expression, geo, or kNN. A kNN bucket prepares against the facet’s complete incoming domain, so its k nearest documents are chosen from the same filtered set the facet sees. There is no bucket-count limit beyond request size.

Query buckets count documents, not value occurrences: a document contributes at most once to a bucket even when several of its values make the query match. Field and range facets count matching field values instead, so one multi-valued document can contribute to several value-derived counts.

The ops map runs independently over each bucket’s documents and accepts the same metrics, nested facets, and per-bucket top_docs as the other facets.

A query facet under facet buckets or collapse groups can reuse a bucket query’s segment membership across parent buckets. It uses the filter cache when available. If the cache declines to build the membership, the first evaluation runs within its parent bucket. A second evaluation on the same segment can build membership for reuse across the rest of the request. Request-owned membership counts against the request memory limit. Queries that need preparation, such as kNN, run separately for each parent bucket.

A faceted UI usually lets a user pick a value and still see the sibling values they could have picked. Put the chosen values in the facet’s selected list: the result set is refined to them, and in the default any mode the facet’s own buckets are counted without that refinement, so the alternatives stay visible with their counts. Sibling operations see the refinement.

Using the author example, select Neal Asher:

POST /collections/authors/_search
{
"query": {
"all": true
},
"fields": ["id", "title_t", "author_name"],
"count_limit": -1,
"ops": {
"authors": {
"field_facet": {
"field": "author_name",
"limit": 10,
"selected": ["Neal Asher"]
}
}
},
"sort": "id"
}
{
"found": 3,
"docs": [
{
"id": "b1",
"title_t": "Gridlinked",
"author_name": "Neal Asher"
},
{
"id": "b2",
"title_t": "The Skinner",
"author_name": "Neal Asher"
},
{
"id": "b4",
"title_t": "Prador Moon",
"author_name": "Neal Asher"
}
],
"ops": {
"authors": {
"buckets": [
{
"val": "Neal Asher",
"count": 3
},
{
"val": "Neal Stephenson",
"count": 2
},
{
"val": "Neal Shusterman",
"count": 1
}
]
}
}
}

The document list holds Asher’s three books, while the facet still shows all three authors. Selection uses the facet’s resolved representation for both normalization and refinement, so a returned bucket value can be sent back as a selection, except for non-finite floating values rendered as JSON null.

selection_mode: "all" requires every selected value instead of any of them, and then the facet’s own buckets are counted over that strict set too.

The rules that apply to every facet kind:

  • selected is supported on facets directly under the query’s ops: not at the root of a full-form request, not under a fusion, and not nested inside another facet.
  • Field facets take values, range facets take bucket lower fences as plain numbers ("selected": [25] picks the bucket that starts at 25), and query facets take bucket names.
  • A selected value that lands in the facet’s ordinary page appears once, at its natural position. Selected values outside the page are appended afterwards in request order with exact counts; range facets keep fence order. Appended buckets are exempt from mincount, may name values absent from the index, and carry the same sub-operation results as ordinary buckets.
  • Selecting on a text facet uses exact-token membership, with the same single-term rule as any_of.

For a query facet, values are bucket names:

"price_tiers": {
"query_facet": {
"buckets": {
"budget": "price_i:[* TO 100]",
"mid": "price_i:[100 TO 1000]"
},
"selected": ["budget","mid"],
"selection_mode": "any"
}
}

A bare field name uses the field’s value binding. In the author example, the _name template sets defaults.value to s, so a facet on author_name uses the string variant and counts whole names such as Neal Asher.

To count individual words instead, use author_name__self. The __self selector bypasses that default and selects the primary analyzed text:

POST /collections/authors/_search
{
"query": {
"all": true
},
"limit": 0,
"count_limit": -1,
"ops": {
"words": {
"field_facet": {
"field": "author_name__self",
"limit": -1
}
}
}
}
{
"found": 6,
"docs": [],
"ops": {
"words": {
"buckets": [
{
"val": "neal",
"count": 6
},
{
"val": "asher",
"count": 3
},
{
"val": "stephenson",
"count": 2
},
{
"val": "shusterman",
"count": 1
}
]
}
}
}

An explicit variant selector such as author_name__s also bypasses the default binding. For a text field whose value binding already selects the primary, the bare field name counts words without needing __self.

  • Facets cannot yet sort by metrics containing cardinality or percentile.
  • Field facet sorting takes one key, which must be a metric operation of that facet. Custom count or bucket-value sort orders are not yet supported; omit sort for the default count order.
  • selected is not accepted at the root of a full-form request, under a fusion, or on a nested facet.
  • Range facets may generate at most 100,000 buckets. With sub-operations, at most 1,024 buckets may be returned after filtering, in either bounds mode.

A bucket child can specify domain to change which documents it operates on. With domain.query, it starts from live documents that satisfy every enclosing bucket’s identity, then applies its own query and filters. It drops the matching queries above the child. For example:

"by_brand": {
"field_facet": {
"field": "brand_s",
"ops": {
"in_stock_colors": {
"field_facet": {"field": "color_s"},
"domain": {"query": {"all": true}, "filter": ["stock_i:>0"]}
}
}
}
}

This counts all in-stock colors for each selected brand, even if the list’s query matched fewer variants. A nested reset retains both the outer and inner bucket identities. Field buckets mean membership in that value, range buckets retain their bounds, query buckets retain their predicate, and group buckets retain exact key equality. The scalar missing count has no bucket row for child operations.

The owning list’s filters are dropped unless apply_parent_filters: true is set. That option requires domain.query, even when its value is false. Its filters keep the routing established at the list’s child branch. Without domain.query, domain.filter simply adds filters to the existing bucket documents and does not widen the domain.

A query-facet bucket containing kNN is re-evaluated inside a child’s reset scope, so the child can see a different window from the parent’s counted window. Nested selection buckets run outer to inner, each within the reset query/filters and the identities above it; identities below a selection apply after that window is chosen. A kNN in the reset’s own query or filters also runs within the reset scope, and a kNN-ranked collapsed list retains key equality as its group identity.

Resets may recover documents excluded by the original search, so their cost can exceed operations on matching members. Indexed keys and values can recover small buckets directly; other identities require column walks. Child execution is bounded in bucket blocks, including domains retained for queries that prepare over all segments.