[Docs] Add painless context details for bucket_selector

docs/build.gradle

@@ -1128,3 +1128,33 @@ buildRestTests.setups['remote_cluster_and_leader_index'] = buildRestTests.setups
             index.number_of_shards: 1
             index.soft_deletes.enabled: true
 '''
+
+buildRestTests.setups['seats'] = '''
+  - do:
+        indices.create:
+          index: seats
+          body:
+            settings:
+              number_of_shards: 1
+              number_of_replicas: 0
+            mappings:
+              _doc:
+                properties:
+                  theatre:
+                    type: keyword
+                  cost:
+                    type: long
+  - do:
+        bulk:
+          index: seats
+          type: _doc
+          refresh: true
+          body: |
+            {"index":{}}
+            {"theatre": "Skyline", "cost": 1}
+            {"index":{}}
+            {"theatre": "Graye", "cost": 5}
+            {"index":{}}
+            {"theatre": "Graye", "cost": 8}
+            {"index":{}}
+            {"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 aggregation                | <<painless-bucket-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-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,82 @@
+
+[[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.
+
+For our example, we are going to find the `max` of each bucket, add in a user-defined "base" value, then keep all
+the buckets that are greater than `10`.
+
+Unlike some other aggregation contexts, the `bucket_selector` context must return a boolean `true`/`false`.
+
+[source,Painless]
+--------------------------------------------------
+params.max + params.base_cost > 10
+--------------------------------------------------
+
+Note how all the values are being pulled from the `params` map. Also note how the script is in the form of an expression,
+which returns `true`/`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 added in the script's `params` section, which is also added to the
+`params` variable for use in the script.