[Docs] Add painless context details for bucket_selector (#35162)

Adds docs for the bucket_selector context, an example
and corresponding doc test

Author: polyfractal

docs/build.gradle

@@ -1153,4 +1153,4 @@ buildRestTests.setups['seats'] = '''
             {"index":{}}
             {"theatre": "Graye", "cost": 8}
             {"index":{}}
-            {"theatre": "Skyline", "cost": 10}'''
+            {"theatre": "Skyline", "cost": 10}'''

docs/painless/painless-contexts.asciidoc

@@ -46,6 +46,8 @@ specialized code may define new ways to use a Painless script.
                                     | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
 | Bucket script aggregation         | <<painless-bucket-script-agg-context, Painless Documentation>>
                                     | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation]
+| Bucket selector aggregation       | <<painless-bucket-selector-agg-context, Painless Documentation>>
+                                    | {ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[Elasticsearch Documentation]
 | Watcher condition                 | <<painless-watcher-condition-context, Painless Documentation>>
                                     | {xpack-ref}/condition-script.html[Elasticsearch Documentation]
 | Watcher transform                 | <<painless-watcher-transform-context, Painless Documentation>>

docs/painless/painless-contexts/index.asciidoc

@@ -30,6 +30,8 @@ include::painless-metric-agg-reduce-context.asciidoc[]
 
 include::painless-bucket-script-agg-context.asciidoc[]
 
+include::painless-bucket-selector-agg-context.asciidoc[]
+
 include::painless-analysis-predicate-context.asciidoc[]
 
 include::painless-watcher-condition-context.asciidoc[]

docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc

@@ -0,0 +1,81 @@
+
+[[painless-bucket-selector-agg-context]]
+=== Bucket selector aggregation context
+
+Use a Painless script in an
+{ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[`bucket_selector` aggregation]
+to determine if a bucket should be retained or filtered out.
+
+==== Variables
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query. The parameters
+        include values defined as part of the `buckets_path`.
+
+==== Return
+
+boolean::
+        True if the the bucket should be retained, false if the bucket should be filtered out.
+
+==== API
+
+
+To run this example, first follow the steps in <<painless-context-examples, context examples>>.
+
+The painless context in a `bucket_selector` aggregation provides a `params` map.  This map contains both
+user-specified custom values, as well as the values from other aggregations specified in the `buckets_path`
+property.
+
+Unlike some other aggregation contexts, the `bucket_selector` context must return a boolean `true` or `false`.
+
+This example finds the max of each bucket, adds a user-specified base_cost, and retains all of the
+buckets that are greater than `10`.
+
+[source,Painless]
+--------------------------------------------------
+params.max + params.base_cost > 10
+--------------------------------------------------
+
+Note that the values are extracted from the `params` map. The script is in the form of an expression
+that returns `true` or `false`.  In context, the aggregation looks like this:
+
+[source,js]
+--------------------------------------------------
+GET /seats/_search
+{
+  "size": 0,
+  "aggs": {
+    "theatres": {
+      "terms": {
+        "field": "theatre",
+        "size": 10
+      },
+      "aggs": {
+        "max_cost": {
+          "max": {
+            "field": "cost"
+          }
+        },
+        "filtering_agg": {
+          "bucket_selector": {
+            "buckets_path": { <1>
+              "max": "max_cost"
+            },
+            "script": {
+              "params": {
+                "base_cost": 5 <2>
+              },
+              "source": "params.max + params.base_cost > 10"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:seats]
+<1> The `buckets_path` points to the max aggregations (`max_cost`) and adds `max` variables
+to the `params` map
+<2> The user-specified `base_cost` is also added to the `params` map