Avg bucket aggregation #

A sibling pipeline aggregation computing the average of a metric across another aggregation’s buckets. Bucket aggregations answer “what is the revenue per day / per category / per range”; avg_bucket rolls those per-bucket numbers into one mean — “what does a typical day or category bring in” — without a second query or client-side arithmetic.

"avg_day": { "avg_bucket": { "buckets_path": "per_day>revenue" } }

How it works #

avg_bucket is declared next to the bucket aggregation it consumes (a sibling in the same aggs object) and runs after every regular aggregation has finished — after the merge, too, in a distributed search. It reads the parent’s finished buckets, collects one number per bucket, and divides their sum by their count. The result is a single-value metric ({"value": 56.25}) placed alongside the parent.

The buckets_path names what to collect:

• "per_day>revenue" — the > separates the bucket aggregation from the sub-metric inside each of its buckets. A . works the same way ("range.v").
• The sub-metric must be single-valued (sum, avg, min, max, value_count, cardinality, …). A multi-value metric such as percentiles has no single number to take; a stats sub-agg contributes its sum.
• A bare parent name ("per_day", no separator) aggregates the buckets’ doc_counts instead of a sub-metric.

Gaps follow gap_policy:

• skip (default) — a bucket whose metric is missing or null is left out; it does not count toward the divisor. An empty bucket (doc_count 0, e.g. a declared range no document falls into) is skipped even though its sum serializes as 0.
• insert_zeros — such buckets contribute 0 and still count.

Three range buckets with sums 1, 5, 0 (the last empty) average to 3 under skip — not 2. If every bucket is missing, the result is {"value": null}.

Examples #

Average daily revenue across the date-histogram buckets:

The teaching dataset holds one sale per calendar day, so every bucket holds exactly one document and the daily revenues average 56.25 — 6750 / 120, the same figure the plain avg returns over amount. With multiple sales per day the two diverge: avg_bucket weighs each bucket equally, avg each document.

Use cases #

• Typical period revenue — date_histogram per month plus avg_bucket over the monthly sum(amount): the 16 months in the dataset average 421.875, a steadier baseline than any single month.
• Compare groups, not documents — average the per-category totals of a terms aggregation to say “an average product line brings 1687.5”, immune to how many documents each category happens to have.
• Baseline for alerting — feed avg_bucket into dashboards as the expected value a current bucket is judged against.
• Empty-bucket hygiene — over buckets that can be empty (declared ranges, filters), skip keeps the mean over populated buckets only; switch to insert_zeros when a missing bucket genuinely means zero.

Parameters for avg_bucket #

• buckets_path
  (Required, string) Path to the consumed metric: "<bucket_agg>><metric>".
• format
  (Optional, string) Output number format. Accepted for compatibility; not applied to the value in the current engine.
• gap_policy
  (Optional, string) What to do with missing buckets: skip (default) or insert_zeros.

Related #

• Sibling family: sum_bucket, min_bucket, max_bucket, stats_bucket, extended_stats_bucket, percentiles_bucket
• Document-level counterpart: avg