Stats bucket aggregation
The stats_bucket aggregation is a sibling aggregation that returns a variety of stats (count, min, max, avg, and sum) for the buckets of a previous aggregation.
The specified metric must be numeric, and the sibling aggregation must be a multi-bucket aggregation.
Parameters
The stats_bucket 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. |
gap_policy | Optional | String | The policy to apply to missing data. Valid values are skip and insert_zeros. Default is skip. See Data gaps. |
format | Optional | String | A DecimalFormat formatting string. Returns the formatted output in the aggregation’s <stat>_as_string property. |
Example
The following example creates a date histogram with a one-month interval using the OpenSearch Dashboards e-commerce sample data. The sum sub-aggregation calculates the sum of all bytes for each month. Finally, the stats_bucket aggregation returns the count, avg, sum, min, and max stats from these sums:
GET opensearch_dashboards_sample_data_logs/_search { "size": 0, "aggs": { "visits_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" }, "aggs": { "sum_of_bytes": { "sum": { "field": "bytes" } } } }, "stats_monthly_bytes": { "stats_bucket": { "buckets_path": "visits_per_month>sum_of_bytes" } } } } Example response
The aggregation returns all five basic statistics for the buckets:
{ "took": 4, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 10000, "relation": "gte" }, "max_score": null, "hits": [] }, "aggregations": { "visits_per_month": { "buckets": [ { "key_as_string": "2025-03-01T00:00:00.000Z", "key": 1740787200000, "doc_count": 480, "sum_of_bytes": { "value": 2804103 } }, { "key_as_string": "2025-04-01T00:00:00.000Z", "key": 1743465600000, "doc_count": 6849, "sum_of_bytes": { "value": 39103067 } }, { "key_as_string": "2025-05-01T00:00:00.000Z", "key": 1746057600000, "doc_count": 6745, "sum_of_bytes": { "value": 37818519 } } ] }, "stats_monthly_bytes": { "count": 3, "min": 2804103, "max": 39103067, "avg": 26575229.666666668, "sum": 79725689 } } }