Stats bucket aggregation #

A sibling pipeline aggregation returning count/min/max/avg/sum of a metric across buckets — the stats of the per-bucket values. One call replaces four: where avg_bucket, min_bucket and max_bucket each reduce the bucket list to a single number, stats_bucket returns the whole summary object beside the aggregation it describes.

"day_stats": { "stats_bucket": { "buckets_path": "per_day>revenue" } }

How it works #

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 the stats result object over that sample:

{ "count": 120, "min": 15, "max": 180, "avg": 56.25, "sum": 6750 }

count is the number of buckets that contributed a value — not the sum of their doc_counts.

The buckets_path names what to collect:

• "per_day>revenue" — the > separates the bucket aggregation from the sub-metric inside each bucket; a . separator ("range.v") works identically.
• The sub-metric must be single-valued (sum, avg, min, max, value_count, cardinality, …). A stats sub-agg contributes its sum; multi-value metrics such as percentiles yield nothing.
• A bare parent name ("per_day") profiles the buckets’ doc_counts.

Gaps follow gap_policy:

• skip (default) — a bucket whose metric is missing or null is left out of every statistic, and an empty bucket (doc_count 0, e.g. a declared range nothing fell into) is skipped even though its sum reads 0.
• insert_zeros — such buckets contribute 0 to count, min, and sum.

When no bucket contributes, the result is {"count": 0, "min": null, "max": null, "avg": null, "sum": 0.0}.

Examples #

Each of the 120 single-sale days is one sample, so the daily revenues run from 15 to 180, average 56.25, and total 6750.

Use cases #

• Per-group spread at a glance — count/min/max/avg of the per-category totals of a terms aggregation: how far the best line is from the worst.
• Series envelope — a compact min/avg/max band over daily or monthly buckets, ready for a chart’s shaded range.
• Data-quality check — a suspicious min of 0 (an empty bucket under insert_zeros) or a count smaller than the number of buckets flags gaps in the underlying data.
• Baseline object for dashboards — one metric the UI can slice into the four numbers it needs.

Parameters for 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.

Related #

• Sibling family: avg_bucket, sum_bucket, min_bucket, max_bucket, extended_stats_bucket (adds variance and std deviation), percentiles_bucket
• Document-level counterpart: stats