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.
{ "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. |
Easy multi-select with selected
Section titled “Easy multi-select with selected”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:
{ "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".
Counting groups and distinct keys
Section titled “Counting groups and distinct keys”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.
Field facets
Section titled “Field facets”A field_facet groups by distinct field value. For example, count books in
each category:
{ "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.
Filtering bucket terms
Section titled “Filtering bucket terms”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:
missingstill counts every document in the domain without a value.mincount: 0pads with zero-count terms that pass the filter.selectedbuckets 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.
Expression metrics
Section titled “Expression metrics”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:
{ "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:
cardinalityaccepts 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, andpercentile_rankalso skip NaN and infinity. - Integer
sum,min, andmaxreturn int64 values and accumulate exactly;avgand floating-pointsum,min, andmaxreturn a double. With no contributing values,cardinalityreturns 0 and other aggregates returnnull. Data-dependent overflow or a non-finite result returnsnullwith a response warning. avg,min,max, andpercentileof a date keep their DATE nature and unit (msorns). 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.cardinalityandpercentile_rankreturn plain numbers.sumrequires numeric values. Multiplication, division, unary minus, and unary math turn a date into a plain number.- Decimal
avgandpercentilekeep their scale, likemin,max, andsum. Their results are doubles, in raw units underdecimal_scaled.percentile_rankuses a value-unit bound and returns a percentage in either mode. - For a bare FLOAT column,
percentile_rankrounds its bound to FLOAT, matching range queries. Expression inputs use a double bound.
Accuracy and memory
Section titled “Accuracy and memory”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.
Nested facets
Section titled “Nested facets”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.
Top documents per bucket
Section titled “Top documents per bucket”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.
Range facets
Section titled “Range facets”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.
Data-derived bounds
Section titled “Data-derived bounds”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 * gapfor a global integerk; defaultoriginis 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_scaledinterprets them in raw integer units. - For DATE fixed gaps,
originis a wall-clock phase in the facet zone, expressed in integer field units (msorns). For an ms field,gap: 86400000andorigin: 21600000start days at 06:00 local, including DST days. Luxir applies this phase before resolving local times. Elasticsearch’soffsettranslates the rounded grid in UTC, so nonzero phases can differ near DST changes;originis 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 rejectorigin.
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 histograms
Section titled “Date histograms”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.
Query facets
Section titled “Query facets”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.
Multi-select navigation
Section titled “Multi-select navigation”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:
{ "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:
selectedis supported on facets directly under the query’sops: not at the root of a full-form request, not under afusion, 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" }}Field variants
Section titled “Field variants”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:
{ "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.
Limits
Section titled “Limits”- Facets cannot yet sort by metrics containing
cardinalityorpercentile. - 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
sortfor the default count order. selectedis not accepted at the root of a full-form request, under afusion, 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.
Bucket domain resets
Section titled “Bucket domain resets”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.