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.
Average bucket aggregations
The avg_bucket aggregation is a sibling aggregation that calculates the average of a metric in each bucket of a previous aggregation.
The specified metric must be numeric, and the sibling aggregation must be a multi-bucket aggregation.
Parameters
The avg_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 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 bytes for each month. Finally, the avg_bucket aggregation calculates the average number of bytes per month from these sums:
POST 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"
}
}
}
},
"avg_monthly_bytes": {
"avg_bucket": {
"buckets_path": "visits_per_month>sum_of_bytes"
}
}
}
}
Example response
The aggregation returns the average bytes from the monthly buckets:
{
"took": 43,
"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
}
}
]
},
"avg_monthly_bytes": {
"value": 26575229.666666668
}
}
}