You're viewing version 3.0 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Cumulative sum aggregations
The cumulative_sum aggregation is a parent aggregation that calculates the cumulative sum across the buckets of a previous aggregation.
A cumulative sum is a sequence of partial sums of a given sequence. For example, the cumulative sums of the sequence {a,b,c,…} are a, a+b, a+b+c, and so on. You can use the cumulative sum to visualize the rate of change of a field over time.
Parameters
The cumulative_sum aggregation takes the following parameters.
| Parameter | Required/Optional | Data type | Description |
|---|---|---|---|
buckets_path | Required | String | The path of the aggregation buckets to be aggregated. See Buckets path. |
format | Optional | String | A DecimalFormat formatting string. Returns the formatted output in the aggregation’s value_as_string property. |
Example
The following example creates a date histogram with a one-month interval from the OpenSearch Dashboards e-commerce sample data. The sum subaggregation calculates the sum of all bytes for each month. Finally, the cumulative_sum aggregation calculates the cumulative number of bytes for each month’s bucket:
GET opensearch_dashboards_sample_data_logs/_search
{
"size": 0,
"aggs": {
"sales_per_month": {
"date_histogram": {
"field": "@timestamp",
"calendar_interval": "month"
},
"aggs": {
"no-of-bytes": {
"sum": {
"field": "bytes"
}
},
"cumulative_bytes": {
"cumulative_sum": {
"buckets_path": "no-of-bytes"
}
}
}
}
}
}
Example response
{
"took": 8,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 10000,
"relation": "gte"
},
"max_score": null,
"hits": []
},
"aggregations": {
"sales_per_month": {
"buckets": [
{
"key_as_string": "2025-03-01T00:00:00.000Z",
"key": 1740787200000,
"doc_count": 480,
"no-of-bytes": {
"value": 2804103
},
"cumulative_bytes": {
"value": 2804103
}
},
{
"key_as_string": "2025-04-01T00:00:00.000Z",
"key": 1743465600000,
"doc_count": 6849,
"no-of-bytes": {
"value": 39103067
},
"cumulative_bytes": {
"value": 41907170
}
},
{
"key_as_string": "2025-05-01T00:00:00.000Z",
"key": 1746057600000,
"doc_count": 6745,
"no-of-bytes": {
"value": 37818519
},
"cumulative_bytes": {
"value": 79725689
}
}
]
}
}
}