Max bucket aggregation #

A sibling pipeline aggregation identifying the largest per-bucket metric value — e.g. the best-performing group. Bucket aggregations can sort their own output, but only inside one request’s bucket list; max_bucket lifts the winning number out as a single headline metric next to the breakdown.

"best_seller": { "max_bucket": { "buckets_path": "per_type>revenue" } }

How it works #

max_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 returns their maximum as a single-value metric ({"value": 1800}) placed alongside the parent. Only the value is returned — not which bucket produced it; read the parent’s bucket list (or sort it with bucket_sort) when you need the winner’s key.

The buckets_path names what to collect:

• "per_type>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_type") takes each bucket’s doc_count — the busiest bucket, not the biggest metric.

Gaps follow gap_policy:

• skip (default) — a bucket whose metric is missing or null is left out, 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, which a maximum happily ignores unless every bucket is a gap.

If every bucket is missing, the result is {"value": null}.

Examples #

The four product types bring in 1800, 1800, 1350, 1800, so the largest per-type revenue is 1800 — shared by t-shirt, hat, and sticker.

Use cases #

• Find the strongest group — the category, merchant, or region with the highest total, as one headline number beside the full breakdown.
• Peak of a series — the best day in a date_histogram of daily revenue (over the teaching dataset’s 120 single-sale days the daily maximum is 180).
• Worst-case latency — max of per-service average latencies from a terms over service names: the service to optimize first.
• Capacity ceiling — max requests-per-minute across time buckets to size a deployment.

Parameters for max_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, stats_bucket, extended_stats_bucket, percentiles_bucket
• Document-level counterpart: max