Histogram aggregation

Histogram aggregation #

A multi-bucket aggregation over numeric fields that applies a fixed interval to build the buckets. It answers “how are the values distributed?” — every document lands in exactly one bucket, and the bucket keys form a regular grid over the value axis.

How it works #

Each document’s value v is placed by index arithmetic — bucket index floor((v - offset) / interval) — so a bucket covers the half-open window [key, key + interval). Buckets accumulate in a sorted map, and the response lists them by ascending key.

Median absolute deviation aggregation

Median absolute deviation aggregation #

A single-value metrics aggregation that computes the median absolute deviation — the median of the distances from each value to the median of all values. A robust measure of spread: unlike standard deviation it is not skewed by a few extreme values.

How it works #

The aggregation runs in three steps over the collected values of the field:

1. Compute the median with the same TDigest arithmetic percentiles uses — weight-1 centroids at (i + 0.5) / n, linear interpolation between the two bracketing values.
2. Take each value’s absolute distance to that median, |v − median|.
3. Return the median of those distances, using the same arithmetic again.

Because both medians interpolate, the result can land between observed values (over the 120 teaching sale prices: median 22.5, MAD 7.5 — neither is a price anyone paid). The value is expressed in the same units as the field, so a MAD of 7.5 on prices means “a typical sale is $7.50 away from the median price”.

Percentiles bucket aggregation

Percentiles bucket aggregation #

A sibling pipeline aggregation computing percentiles of a metric across buckets — e.g. “the daily-revenue p95”. The mean of the per-bucket values answers “what is typical”; percentiles answer “what the whole ladder of buckets looks like” — including the outlier end that a stats_bucket min/max flattens into two numbers.

"day_pcts": { "percentiles_bucket": { "buckets_path": "per_day>revenue" } }

How it works #

percentiles_bucket is declared next to the bucket aggregation it consumes and runs after every regular aggregation — including the distributed merge — has finished. It walks the parent’s finished buckets, collects one number per bucket, sorts them, and evaluates each requested percentile over the sorted sample, returning a {"values": {...}} object keyed by the percentile:

Variable width histogram aggregation

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. Fixed grids go blind where data is sparse and waste resolution where it is dense; the variable-width form spends its buckets where the documents actually are.

How it works #

The engine collects every numeric value, sorts it, and partitions the sorted run into buckets contiguous segments such that the sum of squared distances to each segment’s mean is minimal — the classic one-dimensional k-segmentation problem, solved exactly with dynamic programming and prefix sums (an O(1) cost function per candidate cut). When n × k exceeds 1,048,576 it falls back to equal-count chunking, a linear-time approximation. buckets is capped at the number of distinct values, so asking for more buckets than there are values simply yields one bucket per value.

Weighted average aggregation

Weighted average aggregation #

A single-value metrics aggregation that computes the weighted average of numeric values. Each document contributes value × weight, divided by the total weight — e.g. an average price weighted by quantity sold. When documents are not all equally important, avg is the wrong tool and this is the right one.

How it works #

The engine walks the matching documents once, accumulating Σ(value × weight) in the numerator and Σ weight in the denominator; the result is their quotient. Both sides are computed in the same pass over two columns, so the pairing of a document’s value with its own weight is never lost.

Date histogram aggregation

Date histogram aggregation #

This multi-bucket aggregation is similar to the normal histogram, but it can only be used with date fields. Dates are represented internally as epoch milliseconds, so the plain histogram can technically run on them too — but calendar intervals are not a fixed length (a month is 28–31 days), which is exactly what this aggregation handles.

How it works #

Date fields store epoch milliseconds at ingest, and the aggregation builds its grid on those numbers. calendar_interval and fixed_interval select between two grid types (exactly one must be set):

Stats aggregation

Stats aggregation #

A multi-value metrics aggregation that computes basic statistics (min, max, sum, count, avg) over numeric values extracted from the aggregated documents. It is avg, min, max and sum folded into one request — the five numbers most dashboards put side by side, for the price of one column scan.

How it works #

The engine walks the matching documents once, maintaining a running count, sum, minimum and maximum; avg is derived at the end as sum / count. Everything is exact — no sampling, no sketches. Values are coerced to doubles as they are read: integers, floats and booleans (true = 1, false = 0) contribute, non-numeric values such as keyword strings do not.

Auto date histogram aggregation

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. It solves the cold-start problem of time charts: when you do not know whether the data spans minutes or years, you state the resolution you want on screen and let the ladder decide the unit.

How it works #

The engine reads every date value (epoch milliseconds), takes the data extent max − min, and divides by the buckets target to get a rough per-bucket width. That width is matched against a fixed ladder, and the smallest interval that covers it wins: 1s, 1m, 5m, 10m, 30m, 1h, 6h, 12h, 1d, 1w as fixed intervals; beyond a week the calendar units month, quarter, year (and multi-year multiples for very long extents). The pick is one closed-form step, not an iterative search.

Extended stats aggregation

Extended stats aggregation #

A multi-value metrics aggregation extending stats with squares, variance, standard deviation and their lower/upper bounds. Where stats says what the values are, extended_stats says how tightly they cluster around the mean — the input for outlier bands, quality gates and anything else built on “how unusual is this value”.

How it works #

The engine walks the matching documents once, maintaining a running count, sum, sum_of_squares, minimum and maximum — the same single pass as stats, plus one multiply-add for the squares. Everything downstream is derived from these raw moments, and is exact (no sampling, no sketches):

Derivative aggregation

Derivative aggregation #

A parent pipeline aggregation computing the difference between each bucket’s metric and the previous bucket’s — “how much did it change”. A time series says where you are; the derivative says which way and how fast you are moving, bucket by bucket. The first bucket has no predecessor and answers null.

"delta": { "derivative": { "buckets_path": "revenue" } }

How it works #

derivative is declared inside the multi-bucket aggregation it decorates (the parent style), next to the metric it consumes. After the buckets are built, the engine walks them in order and attaches current − previous to each bucket under the pipeline’s own name: