Bucket aggregations on INFINI Pizza

Terms aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Terms aggregation #

A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.

Examples #

POST /_search
{
 "aggs": {
 "genres": {
 "terms": {
 "field": "genre"
 }
 }
 }
}

Response:

{
 ...
 "aggregations": {
 "genres": {
 "doc_count_error_upper_bound": 0,
 "sum_other_doc_count": 0,
 "buckets": [
 {
 "key": "electronic",
 "doc_count": 6
 },
 {
 "key": "rock",
 "doc_count": 3
 },
 {
 "key": "jazz",
 "doc_count": 2
 }
 ]
 }
 }
}

Parameters for `terms` #

field
(Required, string) Field you wish to aggregate.
size
(Optional, integer) Maximum number of buckets to return. Defaults to 10.
min_doc_count
(Optional, integer) Drop buckets with fewer matching documents. Defaults to 1; 0 keeps empty buckets — only meaningful together with an explicit include list.
missing
(Optional, value) Value substituted for documents without the field (any scalar; those documents land in one bucket keyed by it).
include
(Optional) Restricts bucket keys: an exact-value array, a wildcard string (prefix* / *suffix), or { "partition": <p>, "num_partitions": <n> }.
exclude
(Optional) Excludes bucket keys: an exact-value array or a wildcard string (negated include).
aggs
(Optional, object) Nested sub-aggregations, computed per bucket.

Multi terms aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Multi terms aggregation #

A multi-bucket aggregation like terms, but the bucket key is a TUPLE of values from several fields — e.g. every (merchant, status) combination.

Example #

Each bucket’s key is an array [merchant, status].

Rare terms aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Rare terms aggregation #

A multi-bucket aggregation that keeps only RARE terms — bucket keys whose document count is at or below max_doc_count. The mirror image of terms for finding the long tail.

Example #

Every product type sells ≥10 times; raise the bar to 15 and only sticker (10 sales) survives:

Parameters for `rare_terms` #

field
(Required, string) Keyword field you wish to aggregate.
max_doc_count
(Optional, integer, default: 1) Maximum document count for a term to be considered rare.
include / exclude
(Optional) Restrict candidate terms (exact values or wildcard patterns).

Significant terms aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Significant terms aggregation #

A multi-bucket aggregation returning terms that are unusually frequent in the current scope (foreground) compared with the whole index (background) — the classic “what’s special about this subset” query.

Example #

Which merchants over-index inside pending sales?

Buckets carry doc_count (foreground) and bg_count (background) — with evenly-distributed demo data the scores stay low; skew your own data and the winners surface.

Range aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Range aggregation #

A multi-bucket aggregation over numeric fields where each bucket is a user-defined range.

Examples #

POST /sales/_search
{
 "aggs": {
 "price_ranges": {
 "range": {
 "field": "price",
 "ranges": [
 { "to": 100 },
 { "from": 100, "to": 200 },
 { "from": 200 }
 ]
 }
 }
 }
}

Response:

Date range aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Date range aggregation #

A multi-bucket aggregation like range, but for date fields. Each bucket is a from/to interval; bounds accept epoch milliseconds.

Example #

Split logs at 2024-06-16 (epoch millis 1718534400000):

The query narrows the scope to the second half of June; the first bucket is then empty and the second holds every scoped log.

Histogram aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Histogram aggregation #

A multi-bucket aggregation over numeric fields that applies a fixed interval to build the buckets.

Examples #

POST /sales/_search
{
 "aggs": {
 "prices": {
 "histogram": {
 "field": "price",
 "interval": 50
 }
 }
 }
}

Response:

{
 ...
 "aggregations": {
 "prices": {
 "buckets": [
 { "key": 0.0, "doc_count": 2 },
 { "key": 50.0, "doc_count": 4 },
 { "key": 100.0, "doc_count": 1 }
 ]
 }
 }
}

Parameters for `histogram` #

field
(Required, string) Field you wish to aggregate (must be numeric).
interval
(Required, number) Bucket width.
offset
(Optional, number, default: 0.0) Shift the bucket boundaries.
min_doc_count
(Optional, integer, default: 0) Only return buckets with at least this many documents.
hard_bounds
(Optional, object) Restrict bucket generation to [min, max) — buckets fully outside are dropped even with min_doc_count: 0.
extended_bounds
(Optional, object) Widen the bucket range beyond the data extent (empty buckets are materialized up to these bounds when min_doc_count is 0). Can only extend, never shrink below the data extent.
aggs
(Optional, object) Nested sub-aggregations, computed per bucket.

For date fields, see the date histogram aggregation.

Variable width histogram aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Variable width histogram aggregation #

A multi-bucket aggregation like histogram, but bucket edges adapt to the data so each bucket holds roughly the same number of documents.

Example #

Each bucket reports its min/max range and doc_count; dense price regions get narrower buckets.

Date histogram aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Date histogram aggregation #

This multi-bucket aggregation is similar to the normal histogram, but it can only be used with date or date range values. Because dates are represented internally in Elasticsearch as long values, it is possible, but not as accurate, to use the normal histogram on dates as well. The main difference in the two APIs is that here the interval can be specified using date/time expressions. Time-based data requires special support because time-based intervals are not always a fixed length.

Auto date histogram aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Auto date histogram aggregation #

A multi-bucket aggregation like date_histogram, but you choose the NUMBER of buckets and the engine picks the interval that best fits.

Example #

Ask for three buckets over the sales timeline:

The engine returns roughly monthly buckets with an interval hint on the result.

IP range aggregation

Mon, 01 Jan 0001 00:00:00 +0000

IP range aggregation #

A multi-bucket aggregation like range, but for IP addresses — buckets are CIDR masks or from/to IP bounds.

Example #

The demo dataset has no IP-typed field (hosts are names like web-01), so the bucket is structurally valid but empty:

On an ip field, each bucket counts the addresses inside its subnet.

Filter aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Filter aggregation #

A single-bucket aggregation that narrows the documents a nested aggregation runs on, with a query acting as the filter condition.

Examples #

Average price of t-shirt sales only:

POST /sales/_search
{
 "aggs": {
 "t_shirts": {
 "filter": { "term": { "field": "type", "value": "t-shirt" } },
 "aggs": {
 "avg_price": { "avg": { "field": "price" } }
 }
 }
 }
}

Parameters for `filter` #

<filter query>
(Required, query) The filter condition — any single query clause in the map form, e.g. {"term": {...}}.
aggs
(Required, object) Nested sub-aggregations, computed over only the matching documents.

For multiple named filters in one aggregation, see filters.

Filters aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Filters aggregation #

A multi-bucket aggregation where each bucket is defined by a named filter — all filters run over the same document set, giving per-filter counts (and nested sub-aggregations) side by side.

Examples #

POST /logs/_search
{
 "aggs": {
 "messages": {
 "filters": {
 "filters": {
 "errors": { "match": { "field": "level", "query": "error" } },
 "warnings": { "match": { "field": "level", "query": "warn" } }
 }
 }
 }
 }
}

An anonymous array of filters is also accepted; its buckets are keyed "0", "1", …

Adjacency matrix aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Adjacency matrix aggregation #

A multi-bucket aggregation returning every named filter’s document set plus their pairwise INTERSECTIONS — the cross product view of several filters.

Example #

hats and delivered filters, and the documents matching both:

Buckets: hats (30), delivered (40) and delivered&hats (10); empty intersections are skipped.

Global aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Global aggregation #

A single-bucket aggregation whose nested aggregations run over all documents in the search context, ignoring the query scope.

Examples #

Compare the query’s average price against the whole dataset’s:

POST /sales/_search
{
 "query": { "term": { "field": "type", "value": "t-shirt" } },
 "aggs": {
 "all_products": {
 "global": {},
 "aggs": {
 "avg_price": { "avg": { "field": "price" } }
 }
 }
 }
}

Parameters for `global` #

aggs
(Required, object) Nested sub-aggregations — the whole point of global: they run over every document, not just the query’s matches.

Missing aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Missing aggregation #

A single-bucket aggregation of the documents that have no indexed value for a field — the inverse of the exists query.

Examples #

POST /sales/_search
{
 "aggs": {
 "no_price": {
 "missing": { "field": "price" }
 }
 }
}

Parameters for `missing` #

field
(Required, string) Field to check for missing values.
aggs
(Optional, object) Nested sub-aggregations, computed over the documents missing the field.

Sampler aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Sampler aggregation #

A single-bucket aggregation that keeps only a sample of the matching documents before running its sub-aggregations — used to cut aggregation cost on very large result sets.

Example #

Sample 60 documents, then count types inside the sample:

Parameters for `sampler` #

shard_size
(Optional, integer, default: 100000) Sample size per shard.
aggs
(Optional, object) Sub-aggregations computed over the sample.

Diversified sampler aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Diversified sampler aggregation #

Like sampler, but the sample is diversified by a field — up to one (or few) documents per value — so rare categories survive the sampling.

Example #

Sample with at most one document per product type: all four types appear instead of being dominated by t-shirt:

Parameters for `diversified_sampler` #

shard_size
(Optional, integer, default: 100000) Sample size per shard.
field
(Required, string) Field used to diversify the sample.
max_docs_per_value
(Optional, integer, default: 1) Documents kept per distinct value.

Geo distance aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Geo distance aggregation #

A multi-bucket aggregation like range, but buckets are distance rings around a geo_point origin.

Example #

Ring the Beijing area origin at 500 km:

Two places fall inside 500 km, thirteen beyond — matching the geo_distance query answer.

Geohash grid aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Geohash grid aggregation #

A multi-bucket aggregation that groups geo_point values into geohash cells — the building block of map clustering.

Example #

Precision 2 (~1,250 km cells):

Bucket keys are geohash strings (wt, ws, …) — render them on a map tile layer.

Geotile grid aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Geotile grid aggregation #

A multi-bucket aggregation grouping geo_point values into zoom/x/y map tiles — the native grid of web maps.

Example #

Zoom 5 tiles:

Keys like 5/26/13 address the tile at zoom 5, column 26, row 13.

Nested aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Nested aggregation #

A single-bucket aggregation that scopes its sub-aggregations to a nested object path. Nested field values are addressable as dotted columns, so sub-aggregations read variants.color style fields directly.

reverse_nested (only valid inside a nested aggregation) jumps back out to the parent-document scope.

Example #

Products carry a variants array; aggregate one value per parent product inside the nested scope, then reverse back out:

Parameters for `nested` #

path
(Required, string) Path of the nested object (dotted).
aggs
(Optional, object) Sub-aggregations in nested scope.

Parameters for `reverse_nested` #

aggs
(Optional, object) Sub-aggregations back in the parent scope.

Children aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Children aggregation #

A single-bucket aggregation that scopes its sub-aggregations to the child documents of a relation field (parent-child joins).

Engine note: the current implementation runs sub-aggregations over the scoped document set keyed by the relation; it does not resolve per-parent child sets.

Example #

Articles carry a related_to relation; look at the relation’s child side:

Parameters for `children` #

type
(Required, string) Name of the child relation to aggregate.
aggs
(Optional, object) Sub-aggregations over the child documents.

Composite aggregation

Mon, 01 Jan 0001 00:00:00 +0000

Composite aggregation #

Paginated multi-source bucket aggregation: the composite key is a tuple built from several sources (a terms field, a histogram interval, a date_histogram, a geotile_grid), and pages of buckets are pulled with an after cursor — the way to stream all combinations without oversizing size.

Examples #

Page through merchant × day combinations:

POST /sales/_search
{
 "aggs": {
 "matrix": {
 "composite": {
 "size": 100,
 "sources": [
 { "merchant": { "terms": { "field": "merchant" } } },
 { "day": { "date_histogram": { "field": "date", "calendar_interval": "day" } } }
 ],
 "after": { "merchant": "shop_b", "day": 1700000000000 }
 }
 }
 }
}

Each response page carries an after_key; pass it back as after to fetch the next page, until a page returns no after_key.

Bucket aggregations on INFINI Pizza

Terms aggregation

Terms aggregation #

Examples #

Parameters for terms #

Multi terms aggregation

Multi terms aggregation #

Example #

Rare terms aggregation

Rare terms aggregation #

Example #

Parameters for rare_terms #

Significant terms aggregation

Significant terms aggregation #

Example #

Range aggregation

Range aggregation #

Examples #

Date range aggregation

Date range aggregation #

Example #

Histogram aggregation

Histogram aggregation #

Examples #

Parameters for histogram #

Variable width histogram aggregation

Variable width histogram aggregation #

Example #

Date histogram aggregation

Date histogram aggregation #

Auto date histogram aggregation

Auto date histogram aggregation #

Example #

IP range aggregation

IP range aggregation #

Example #

Filter aggregation

Filter aggregation #

Examples #

Parameters for filter #

Filters aggregation

Filters aggregation #

Examples #

Adjacency matrix aggregation

Adjacency matrix aggregation #

Example #

Global aggregation

Global aggregation #

Examples #

Parameters for global #

Missing aggregation

Missing aggregation #

Examples #

Parameters for missing #

Sampler aggregation

Sampler aggregation #

Example #

Parameters for sampler #

Diversified sampler aggregation

Diversified sampler aggregation #

Example #

Parameters for diversified_sampler #

Geo distance aggregation

Geo distance aggregation #

Example #

Geohash grid aggregation

Geohash grid aggregation #

Example #

Geotile grid aggregation

Geotile grid aggregation #

Example #

Nested aggregation

Nested aggregation #

Example #

Parameters for nested #

Parameters for reverse_nested #

Children aggregation

Children aggregation #

Example #

Parameters for children #

Parameters for `terms` #

Parameters for `rare_terms` #

Parameters for `histogram` #

Parameters for `filter` #

Parameters for `global` #

Parameters for `missing` #

Parameters for `sampler` #

Parameters for `diversified_sampler` #

Parameters for `nested` #

Parameters for `reverse_nested` #

Parameters for `children` #