Bucket selector aggregations
The bucket_selector aggregation is a parent pipeline aggregation that evaluates a script to determine whether buckets returned by a histogram (or date_histogram) aggregation should be included in the final result.
Unlike pipeline aggregations that create new values, the bucket_selector aggregation acts as a filter, keeping or removing entire buckets based on the specified criteria. Use this aggregation to filter buckets based on the computed metrics of a bucket.
Parameters
The bucket_selector aggregation takes the following parameters.
| Parameter | Required/Optional | Data type | Description |
|---|---|---|---|
buckets_path | Required | Object | A map of variable names to bucketed metrics that identify the metrics to be used in the script. The metrics must be numeric. See Script variables. |
script | Required | String or Object | The script to execute. Can be an inline script, stored script, or script file. The script has access to the variable names defined in the buckets_path parameter. Must return a Boolean value. Buckets returning false are removed from the final output. |
gap_policy | Optional | String | The policy to apply to missing data. Valid values are skip and insert_zeros. Default is skip. See Data gaps. |
Example
The following example creates a date histogram with a one-week interval from the OpenSearch Dashboards e-commerce sample data. The sum subaggregation calculates the sum of all sales for each week. Finally, the bucket_selector aggregation filters the resulting weekly buckets, removing all the buckets that do not have a sum of more than $75,000:
GET opensearch_dashboards_sample_data_ecommerce/_search
{
"size": 0,
"aggs": {
"sales_per_week": {
"date_histogram": {
"field": "order_date",
"calendar_interval": "week"
},
"aggs": {
"weekly_sales": {
"sum": {
"field": "taxful_total_price",
"format": "$#,###.00"
}
},
"avg_vendor_spend": {
"bucket_selector": {
"buckets_path": {
"weekly_sales": "weekly_sales"
},
"script": "params.weekly_sales > 75000"
}
}
}
}
}
}
The aggregation returns the sales_per_week buckets that meet the scripted criterion:
{
"took": 3,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 4675,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"sales_per_week": {
"buckets": [
{
"key_as_string": "2025-03-31T00:00:00.000Z",
"key": 1743379200000,
"doc_count": 1048,
"weekly_sales": {
"value": 79448.60546875,
"value_as_string": "$79,448.61"
}
},
{
"key_as_string": "2025-04-07T00:00:00.000Z",
"key": 1743984000000,
"doc_count": 1048,
"weekly_sales": {
"value": 78208.4296875,
"value_as_string": "$78,208.43"
}
},
{
"key_as_string": "2025-04-14T00:00:00.000Z",
"key": 1744588800000,
"doc_count": 1073,
"weekly_sales": {
"value": 81277.296875,
"value_as_string": "$81,277.30"
}
}
]
}
}
}
Because it returns a Boolean rather than a numeric value, the buckets_selector aggregation does not take a format parameter. In this example, the formatted metrics are returned in the value_as_string result by the sum subaggregation. Contrast this with the example in the bucket_script aggregation.