From 630cb9b1af4ef077671ee88354749c9ac191f44f Mon Sep 17 00:00:00 2001 From: Zachary Tong Date: Thu, 1 Nov 2018 10:57:59 -0400 Subject: [PATCH 1/2] [Docs] Add painless context details for bucket_selector Adds docs for the bucket_selector context, an example and corresponding doc test --- docs/build.gradle | 30 +++++++ docs/painless/painless-contexts.asciidoc | 2 + .../painless/painless-contexts/index.asciidoc | 2 + ...nless-bucket-selector-agg-context.asciidoc | 82 +++++++++++++++++++ 4 files changed, 116 insertions(+) create mode 100644 docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc diff --git a/docs/build.gradle b/docs/build.gradle index e247542ee0817..b7d57a3526966 100644 --- a/docs/build.gradle +++ b/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}''' \ No newline at end of file diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc index cc7bc752ec6d9..3c21365951a11 100644 --- a/docs/painless/painless-contexts.asciidoc +++ b/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 | <> | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation] +| Bucket Selector aggregation | <> + | {ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[Elasticsearch Documentation] | Watcher condition | <> | {xpack-ref}/condition-script.html[Elasticsearch Documentation] | Watcher transform | <> diff --git a/docs/painless/painless-contexts/index.asciidoc b/docs/painless/painless-contexts/index.asciidoc index a71fde0be32a0..acdf4267c9c01 100644 --- a/docs/painless/painless-contexts/index.asciidoc +++ b/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[] diff --git a/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc new file mode 100644 index 0000000000000..b4ef3034ea328 --- /dev/null +++ b/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 <>. + +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. \ No newline at end of file From 7f67ac6cd0aba9fc31af3078bb9049c1d7cfb405 Mon Sep 17 00:00:00 2001 From: Zachary Tong Date: Fri, 2 Nov 2018 11:47:29 -0400 Subject: [PATCH 2/2] review tweaks --- docs/painless/painless-contexts.asciidoc | 2 +- ...ainless-bucket-selector-agg-context.asciidoc | 17 ++++++++--------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc index 3c21365951a11..84501617f751a 100644 --- a/docs/painless/painless-contexts.asciidoc +++ b/docs/painless/painless-contexts.asciidoc @@ -46,7 +46,7 @@ specialized code may define new ways to use a Painless script. | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] | Bucket aggregation | <> | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation] -| Bucket Selector aggregation | <> +| Bucket selector aggregation | <> | {ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[Elasticsearch Documentation] | Watcher condition | <> | {xpack-ref}/condition-script.html[Elasticsearch Documentation] diff --git a/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc index b4ef3034ea328..8e20cf77c353d 100644 --- a/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc +++ b/docs/painless/painless-contexts/painless-bucket-selector-agg-context.asciidoc @@ -1,6 +1,6 @@ [[painless-bucket-selector-agg-context]] -=== Bucket Selector aggregation context +=== Bucket selector aggregation context Use a Painless script in an {ref}/search-aggregations-pipeline-bucket-selector-aggregation.html[`bucket_selector` aggregation] @@ -26,18 +26,18 @@ The painless context in a `bucket_selector` aggregation provides a `params` map. 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` or `false`. -Unlike some other aggregation contexts, the `bucket_selector` context must return a boolean `true`/`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 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: +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] -------------------------------------------------- @@ -76,7 +76,6 @@ GET /seats/_search -------------------------------------------------- // CONSOLE // TEST[setup:seats] -<1> the `buckets_path` points to the max aggregations (`max_cost`) and adds `max` variables +<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. \ No newline at end of file +<2> The user-specified `base_cost` is also added to the `params` map \ No newline at end of file