From 4269a20275874d40bfbf66ba3dbe65ce83482ea3 Mon Sep 17 00:00:00 2001 From: Zachary Tong Date: Wed, 31 Oct 2018 14:08:25 -0400 Subject: [PATCH 1/2] [Docs] Add painless context details for bucket_script Fleshes out the details of the bucket_script context, adds an example and corresponding doc test --- docs/build.gradle | 30 +++++++ docs/painless/painless-contexts.asciidoc | 2 +- .../painless/painless-contexts/index.asciidoc | 2 +- .../painless-bucket-agg-context.asciidoc | 21 ----- ...ainless-bucket-script-agg-context.asciidoc | 87 +++++++++++++++++++ 5 files changed, 119 insertions(+), 23 deletions(-) delete mode 100644 docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc diff --git a/docs/build.gradle b/docs/build.gradle index e247542ee0817..377ee7af0c53c 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..ada0109b98cd0 100644 --- a/docs/painless/painless-contexts.asciidoc +++ b/docs/painless/painless-contexts.asciidoc @@ -44,7 +44,7 @@ specialized code may define new ways to use a Painless script. | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] | Metric aggregation reduce | <> | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] -| Bucket aggregation | <> +| Bucket Script aggregation | <> | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation] | Watcher condition | <> | {xpack-ref}/condition-script.html[Elasticsearch Documentation] diff --git a/docs/painless/painless-contexts/index.asciidoc b/docs/painless/painless-contexts/index.asciidoc index a71fde0be32a0..df0c6f71e7798 100644 --- a/docs/painless/painless-contexts/index.asciidoc +++ b/docs/painless/painless-contexts/index.asciidoc @@ -28,7 +28,7 @@ include::painless-metric-agg-combine-context.asciidoc[] include::painless-metric-agg-reduce-context.asciidoc[] -include::painless-bucket-agg-context.asciidoc[] +include::painless-bucket-script-agg-context.asciidoc[] include::painless-analysis-predicate-context.asciidoc[] diff --git a/docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc deleted file mode 100644 index 3bb4cae3d3bab..0000000000000 --- a/docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc +++ /dev/null @@ -1,21 +0,0 @@ -[[painless-bucket-agg-context]] -=== Bucket aggregation context - -Use a Painless script in an -{ref}/search-aggregations-pipeline-bucket-script-aggregation.html[bucket aggregation] -to calculate a value as a result in a bucket. - -*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* - -numeric:: - The calculated value as the result. - -*API* - -The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc new file mode 100644 index 0000000000000..bf0b9ba544aa3 --- /dev/null +++ b/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc @@ -0,0 +1,87 @@ +[[painless-bucket-script-agg-context]] +=== Bucket Script aggregation context + +Use a Painless script in an +{ref}/search-aggregations-pipeline-bucket-script-aggregation.html[`bucket_script` pipeline aggregation] +to calculate a value as a result in a bucket. + +==== 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 + +numeric:: + The calculated value as the result. + +==== API + +The standard <> is available. + +==== Example + +To run this example, first follow the steps in <>. + +The painless context in a `bucket_script` 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 take the values from a `min` and `max` aggregation, subtract them to find +the difference, then add in a "base cost" from a user-specified value. The script looks like this: + +[source,Painless] +-------------------------------------------------- +(params.max - params.min) + params.base_cost +-------------------------------------------------- + +Note how all the values are being pulled from the `params` map. In context, the aggregation looks like this: + +[source,js] +-------------------------------------------------- +GET /seats/_search +{ + "size": 0, + "aggs": { + "theatres": { + "terms": { + "field": "theatre", + "size": 10 + }, + "aggs": { + "min_cost": { + "min": { + "field": "cost" + } + }, + "max_cost": { + "max": { + "field": "cost" + } + }, + "spread_plus_base": { + "bucket_script": { + "buckets_path": { <1> + "min": "min_cost", + "max": "max_cost" + }, + "script": { + "params": { + "base_cost": 5 <2> + }, + "source": "(params.max - params.min) + params.base_cost" + } + } + } + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[setup:seats] +<1> the `buckets_path` points to two aggregations (`min_cost`, `max_cost`) and adds `min`/`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 865133104764f63a2c58647b83250d26634b6c21 Mon Sep 17 00:00:00 2001 From: Zachary Tong Date: Fri, 2 Nov 2018 11:42:14 -0400 Subject: [PATCH 2/2] review tweaks --- docs/painless/painless-contexts.asciidoc | 2 +- .../painless-bucket-script-agg-context.asciidoc | 13 ++++++------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc index ada0109b98cd0..d3f598525a8b7 100644 --- a/docs/painless/painless-contexts.asciidoc +++ b/docs/painless/painless-contexts.asciidoc @@ -44,7 +44,7 @@ specialized code may define new ways to use a Painless script. | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] | Metric aggregation reduce | <> | {ref}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] -| Bucket Script aggregation | <> +| Bucket script aggregation | <> | {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation] | Watcher condition | <> | {xpack-ref}/condition-script.html[Elasticsearch Documentation] diff --git a/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc index bf0b9ba544aa3..5a5306016945d 100644 --- a/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc +++ b/docs/painless/painless-contexts/painless-bucket-script-agg-context.asciidoc @@ -1,5 +1,5 @@ [[painless-bucket-script-agg-context]] -=== Bucket Script aggregation context +=== Bucket script aggregation context Use a Painless script in an {ref}/search-aggregations-pipeline-bucket-script-aggregation.html[`bucket_script` pipeline aggregation] @@ -28,15 +28,15 @@ The painless context in a `bucket_script` 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 take the values from a `min` and `max` aggregation, subtract them to find -the difference, then add in a "base cost" from a user-specified value. The script looks like this: +This example takes the values from a min and max aggregation, calculates the difference, +and adds the user-specified base_cost to the result: [source,Painless] -------------------------------------------------- (params.max - params.min) + params.base_cost -------------------------------------------------- -Note how all the values are being pulled from the `params` map. In context, the aggregation looks like this: +Note that the values are extracted from the `params` map. In context, the aggregation looks like this: [source,js] -------------------------------------------------- @@ -81,7 +81,6 @@ GET /seats/_search -------------------------------------------------- // CONSOLE // TEST[setup:seats] -<1> the `buckets_path` points to two aggregations (`min_cost`, `max_cost`) and adds `min`/`max` variables +<1> The `buckets_path` points to two aggregations (`min_cost`, `max_cost`) and adds `min`/`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 script's `params` map \ No newline at end of file