Sum bucket aggregation #

A sibling pipeline aggregation computing the sum of a metric across another aggregation’s buckets — e.g. “total of the daily totals”. Where avg_bucket characterizes the typical bucket, sum_bucket re-totals the per-bucket values, which is how you grand-total a figure that was only computed per group.

"grand_total": { "sum_bucket": { "buckets_path": "per_day>revenue" } }

How it works #

sum_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 adds them up into a single-value metric ({"value": 6750}) 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 bucket; a . separator ("str_terms.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") totals the buckets’ doc_counts.

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; with all-numeric buckets the total is unchanged, the difference only shows with null metrics.

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

Examples #

The result equals the plain sum over all documents (6750).

Use cases #

• Grand total of a grouped report — total the per-category sums of a terms aggregation to append an “all categories” line without re-running the query.
• Total across a filtered slice — when the search already filters to a subset, sum_bucket re-totals the per-bucket figures of just that subset.
• Total of a derived metric — sum per-bucket averages or rates (over buckets holding equal document counts, e.g. per-day counts) where a document-level sum is meaningless.
• Count the buckets’ documents — buckets_path: "per_day" (bare) totals doc_count across buckets, a quick cross-check against hits.total.

Parameters for sum_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) skip (default) or insert_zeros.

Related #

• Sibling family: avg_bucket, min_bucket, max_bucket, stats_bucket, extended_stats_bucket, percentiles_bucket
• Document-level counterpart: sum