Cumulative sum aggregation #

A parent pipeline aggregation adding a running total column to each bucket — the metric plus every earlier bucket’s. A histogram says what each period brought in; the cumulative sum says where the whole span stands at every point along it, without a second query or client-side arithmetic.

"running": { "cumulative_sum": { "buckets_path": "revenue" } }

How it works #

cumulative_sum is declared inside the multi-bucket aggregation it decorates, next to the metric it consumes. After the buckets are built, the engine walks them in order and attaches the running total to each bucket under the pipeline’s own name:

"buckets": [
  { "key_as_string": "2024-01-01", "doc_count": 1,
    "revenue": { "value": 15 }, "running": { "value": 15.0 } },
  { "key_as_string": "2024-01-05", "doc_count": 1,
    "revenue": { "value": 30 }, "running": { "value": 45.0 } }
]

Details verified against the engine:

• buckets_path addresses a metric in the same bucket: a bare name ("revenue"), optionally with a .value suffix. "_count" accumulates the bucket document counts instead of a sub-metric.
• Bucket order is the parent’s output order — chronological for a date_histogram, which is what makes a running total meaningful.
• A bucket whose metric is missing answers null and the total freezes: the next bucket resumes from the last accumulated value. A gap never resets the column.
• An empty bucket (doc_count 0) contributes nothing under the default skip gap policy; insert_zeros lets it add 0.

A second, engine-specific placement also works: declaring cumulative_sum next to the bucket aggregation, with buckets_path: "per_day>revenue", returns a standalone buckets array (keys 0..n−1) holding one value per consumed bucket — the same numbers, outside the parent’s response.

Examples #

The teaching dataset sells exactly once per day, so each running is the sum of that day’s amount and every earlier one. The final bucket’s running equals the plain total (6750). Switch the interval to "month" and the column steps through the 16 month buckets — 270 after January 2024, 765 after February, … 6750 after April 2025.

Use cases #

• Year-to-date revenue — a monthly date_histogram with sum(amount) plus cumulative_sum draws the progress-to-target line a finance dashboard needs; the last point is always the plain grand total.
• Cumulative volume — buckets_path: "_count" turns any bucketed count (messages per hour, orders per day) into “total handled so far”, the shape capacity planning consumes.
• Budget burn — accumulate spend per period and lay it against a straight plan line; the gap between the two curves is the story.
• Defect totals — accumulate per-bucket error or defect counts into a monotonically rising line; flat stretches mean clean periods.

Parameters for cumulative_sum #

• buckets_path
  (Required, string) Path to the consumed metric in the same bucket.
• 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 #

• derivative — the bucket-to-bucket change feeding the total; serial_diff — the change lag buckets back
• cumulative_cardinality — the same running accumulation over per-bucket distinct counts
• sum_bucket — the grand total alone, without the per-bucket column