Extended stats bucket aggregation #

A sibling pipeline aggregation extending stats_bucket with variance, standard deviation and their sampling variants of the per-bucket metric distribution. Use it when the spread of the per-bucket numbers matters — how uneven the days or categories are — not just their min/avg/max envelope.

"day_xstats": {
  "extended_stats_bucket": { "buckets_path": "per_day>revenue" }
}

How it works #

extended_stats_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, and emits an extended_stats-shaped result over that sample:

{
  "count": 120, "min": 15, "max": 180, "avg": 56.25, "sum": 6750,
  "sum_of_squares": 614250,
  "variance": 1954.6875, "variance_population": 1954.6875,
  "variance_sampling": 1971.11,
  "std_deviation": 44.21, "std_deviation_population": 44.21,
  "std_deviation_sampling": 44.4
}

variance and std_deviation are the population forms (sum_of_squares / n − mean², clamped at zero); the _sampling variants use the n − 1 denominator (defined from two buckets on). count is the number of buckets that contributed a value — not the sum of their doc_counts.

Two features are not implemented here: there is no sigma parameter (a sigma in the request is accepted and ignored), and the result carries no std_deviation_bounds object — take avg ± k × std_deviation yourself if you need a band.

The buckets_path and gap rules are the family’s:

• "per_day>revenue" (> or . separator) — the sub-metric inside each bucket; it must be single-valued (sum, avg, min, max, value_count, cardinality, …). A stats sub-agg contributes its sum. A bare parent name profiles the buckets’ doc_counts.
• skip (default) leaves buckets with a missing metric — and empty buckets (doc_count 0) whose sum reads 0 — out of every statistic; insert_zeros has them contribute 0.

With no contributing bucket the numeric fields are null and count is 0.

Examples #

The 120 daily revenues have a population standard deviation of about 44.2 around the 56.25 mean — days swing widely relative to their average.

Use cases #

• Volatility of a series — std deviation of daily or monthly revenue buckets: a high std_deviation / avg flags an erratic business rather than a merely small one.
• Outlier-prone groups — variance of the per-category totals of a terms aggregation to catch one dominant line among many.
• Anomaly banding — combine avg and std_deviation (population) into a mean ± 2σ envelope for dashboards, computed bucket-side.
• Small-sample care — with a handful of buckets, read the _sampling variants; the population forms underestimate spread.

Parameters for extended_stats_bucket #

• buckets_path
  (Required, string) Path to the consumed metric.
• format
  (Optional, string) Output number format. Accepted for compatibility; not applied to the value in the current engine.
• gap_policy
  (Optional, string) skip (default) or insert_zeros.
• sigma
  Not implemented — accepted for compatibility and ignored; the result has no std_deviation_bounds.

Related #

• Sibling family: avg_bucket, sum_bucket, min_bucket, max_bucket, stats_bucket (the same sample without variance), percentiles_bucket
• Document-level counterpart: extended_stats