From 16a31df1801800c3e88dfbafcd1864699c0cc59d Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Mon, 1 Mar 2021 15:39:33 -0500 Subject: [PATCH 1/6] [DOCS] Reformat avg bucket agg reference --- docs/Versions.asciidoc | 3 +- .../pipeline/avg-bucket-aggregation.asciidoc | 158 ++++++++++-------- 2 files changed, 93 insertions(+), 68 deletions(-) diff --git a/docs/Versions.asciidoc b/docs/Versions.asciidoc index 710293b4d172b..74026becda37d 100644 --- a/docs/Versions.asciidoc +++ b/docs/Versions.asciidoc @@ -15,7 +15,8 @@ include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[] /////// Javadoc roots used to generate links from Painless's API reference /////// -:java11-javadoc: https://docs.oracle.com/en/java/javase/11/docs/api +:javadoc: https://docs.oracle.com/en/java/javase/{jdk_major}/docs/api +:java11-javadoc: https://docs.oracle.com/en/java/javase/11/docs/api :lucene-core-javadoc: https://lucene.apache.org/core/{lucene_version_path}/core ifeval::["{release-state}"=="unreleased"] diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index 27ad8fbbe5ec3..6de270b5d55c1 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -1,44 +1,67 @@ [[search-aggregations-pipeline-avg-bucket-aggregation]] -=== Avg bucket aggregation +=== Average bucket aggregation ++++ -Avg bucket +Average bucket ++++ -A sibling pipeline aggregation which calculates the (mean) average value of a specified metric in a sibling aggregation. -The specified metric must be numeric and the sibling aggregation must be a multi-bucket aggregation. +A sibling pipeline aggregation which calculates the mean value of a specified +metric in a sibling aggregation. The specified metric must be numeric and the +sibling aggregation must be a multi-bucket aggregation. [[avg-bucket-agg-syntax]] ==== Syntax -An `avg_bucket` aggregation looks like this in isolation: - [source,js] --------------------------------------------------- +---- { "avg_bucket": { - "buckets_path": "the_sum" + "buckets_path": "the_sum", + "gap_policy": "skip", + "format": "#0.00;(#0.00)" } } --------------------------------------------------- +---- // NOTCONSOLE [[avg-bucket-params]] -.`avg_bucket` Parameters -[options="header"] -|=== -|Parameter Name |Description |Required |Default Value -|`buckets_path` |The path to the buckets we wish to find the average for (see <> for more - details) |Required | - |`gap_policy` |The policy to apply when gaps are found in the data (see <> for more - details) |Optional |`skip` - |`format` |format to apply to the output value of this aggregation |Optional | `null` -|=== - -The following snippet calculates the average of the total monthly `sales`: +==== Parameters + +`buckets_path`:: +(Required, string) +Path to the buckets to average. For syntax, see <>. + +`gap_policy`:: +(Optional, string) +Policy to apply when gaps are found in the data. For valid values, see +<>. Defaults to `skip`. + +`format`:: +(Optional, string) +{javadoc}/java.base/java/text/DecimalFormat.html[DecimalFormat pattern] for the +output value. If specified, the formatted value is returned in the aggregation's +`value_as_string` property. + +[[avg-bucket-agg-response]] +==== Response body + +`value`:: +(float) +Mean average value for the metric specified in `buckets_path`. + +`value_as_string`:: +(string) +Formatted output value for the aggregation. This property is only provided if +a `format` is specified in the request. + +[[avg-bucket-agg-ex]] +==== Example + +The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate +average sales per month: [source,console] --------------------------------------------------- -POST /_search +---- +POST _search { "size": 0, "aggs": { @@ -57,62 +80,63 @@ POST /_search }, "avg_monthly_sales": { "avg_bucket": { - "buckets_path": "sales_per_month>sales" <1> + "buckets_path": "sales_per_month>sales", <1> + "format": "#,##0.00" } } } } - --------------------------------------------------- +---- // TEST[setup:sales] -<1> `buckets_path` instructs this avg_bucket aggregation that we want the (mean) average value of the `sales` aggregation in the +<1> Calculates the mean value of the `sales` aggregation in the `sales_per_month` date histogram. -And the following may be the response: +The request returns the following response: [source,console-result] --------------------------------------------------- +---- { - "took": 11, - "timed_out": false, - "_shards": ..., - "hits": ..., - "aggregations": { - "sales_per_month": { - "buckets": [ - { - "key_as_string": "2015/01/01 00:00:00", - "key": 1420070400000, - "doc_count": 3, - "sales": { - "value": 550.0 - } - }, - { - "key_as_string": "2015/02/01 00:00:00", - "key": 1422748800000, - "doc_count": 2, - "sales": { - "value": 60.0 - } - }, - { - "key_as_string": "2015/03/01 00:00:00", - "key": 1425168000000, - "doc_count": 2, - "sales": { - "value": 375.0 - } - } - ] - }, - "avg_monthly_sales": { - "value": 328.33333333333333 - } - } + "took": 11, + "timed_out": false, + "_shards": ..., + "hits": ..., + "aggregations": { + "sales_per_month": { + "buckets": [ + { + "key_as_string": "2015/01/01 00:00:00", + "key": 1420070400000, + "doc_count": 3, + "sales": { + "value": 550.0 + } + }, + { + "key_as_string": "2015/02/01 00:00:00", + "key": 1422748800000, + "doc_count": 2, + "sales": { + "value": 60.0 + } + }, + { + "key_as_string": "2015/03/01 00:00:00", + "key": 1425168000000, + "doc_count": 2, + "sales": { + "value": 375.0 + } + } + ] + }, + "avg_monthly_sales": { + "value": 328.33333333333333, + "value_as_string": "328.33" + } + } } --------------------------------------------------- +---- // TESTRESPONSE[s/"took": 11/"took": $body.took/] // TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/] // TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/] From 105e3b162757da5e0ac7f164cb42f03200143f50 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 2 Mar 2021 10:59:13 -0500 Subject: [PATCH 2/6] Reuse syntax block --- .../pipeline/avg-bucket-aggregation.asciidoc | 22 +++++++------------ 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index 6de270b5d55c1..08d0932d1c422 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -11,15 +11,9 @@ sibling aggregation must be a multi-bucket aggregation. [[avg-bucket-agg-syntax]] ==== Syntax -[source,js] +[source,js,indent=0] ---- -{ - "avg_bucket": { - "buckets_path": "the_sum", - "gap_policy": "skip", - "format": "#0.00;(#0.00)" - } -} +include::avg-bucket-aggregation.asciidoc[tag=avg-bucket-agg-syntax] ---- // NOTCONSOLE @@ -59,7 +53,7 @@ a `format` is specified in the request. The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate average sales per month: -[source,console] +[source,console,subs="+specialchars"] ---- POST _search { @@ -79,19 +73,19 @@ POST _search } }, "avg_monthly_sales": { +// tag::avg-bucket-agg-syntax[] "avg_bucket": { - "buckets_path": "sales_per_month>sales", <1> - "format": "#,##0.00" + "buckets_path": "sales_per_month>sales", + "gap_policy": "skip", + "format": "#,##0.00;(#,##0.00)" } +// end::avg-bucket-agg-syntax[] } } } ---- // TEST[setup:sales] -<1> Calculates the mean value of the `sales` aggregation in the -`sales_per_month` date histogram. - The request returns the following response: [source,console-result] From ee06c0dae9cc1d7fe3aa194fcec726f3578424a5 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 2 Mar 2021 11:00:16 -0500 Subject: [PATCH 3/6] Remove unneeded subs customization --- .../aggregations/pipeline/avg-bucket-aggregation.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index 08d0932d1c422..62aefcdeedac4 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -53,7 +53,7 @@ a `format` is specified in the request. The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate average sales per month: -[source,console,subs="+specialchars"] +[source,console] ---- POST _search { From deb1334e3717e23739c1de20f291aff24b3f613b Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 2 Mar 2021 13:22:16 -0500 Subject: [PATCH 4/6] Add callouts for tag comments --- .../pipeline/avg-bucket-aggregation.asciidoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index 62aefcdeedac4..fb0894ceeec1a 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -53,7 +53,7 @@ a `format` is specified in the request. The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate average sales per month: -[source,console] +[source,console,subs="specialchars+"] ---- POST _search { @@ -73,19 +73,22 @@ POST _search } }, "avg_monthly_sales": { -// tag::avg-bucket-agg-syntax[] +// tag::avg-bucket-agg-syntax[] <1> "avg_bucket": { "buckets_path": "sales_per_month>sales", "gap_policy": "skip", "format": "#,##0.00;(#,##0.00)" } -// end::avg-bucket-agg-syntax[] +// end::avg-bucket-agg-syntax[] <2> } } } ---- // TEST[setup:sales] +<1> Start of the `avg_bucket` configuration. +<2> End of the `avg_bucket` configuration. + The request returns the following response: [source,console-result] From e67a10f0a05ded3ffb88ac584eaa1a9bfb9eb383 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 2 Mar 2021 13:23:12 -0500 Subject: [PATCH 5/6] Reword callout --- .../aggregations/pipeline/avg-bucket-aggregation.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index fb0894ceeec1a..3b3a9a76cd04f 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -86,8 +86,8 @@ POST _search ---- // TEST[setup:sales] -<1> Start of the `avg_bucket` configuration. -<2> End of the `avg_bucket` configuration. +<1> Start of the `avg_bucket` configuration. This comment is not part of the example. +<2> End of the `avg_bucket` configuration. This comment is not part of the example. The request returns the following response: From 2e7591ac60e7fd54201b5e57f71866ce880bfb02 Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Tue, 2 Mar 2021 13:24:08 -0500 Subject: [PATCH 6/6] Reword callout --- .../aggregations/pipeline/avg-bucket-aggregation.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc index 3b3a9a76cd04f..e68cf2bc646f7 100644 --- a/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc +++ b/docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc @@ -86,8 +86,8 @@ POST _search ---- // TEST[setup:sales] -<1> Start of the `avg_bucket` configuration. This comment is not part of the example. -<2> End of the `avg_bucket` configuration. This comment is not part of the example. +<1> Start of the `avg_bucket` configuration. Comment is not part of the example. +<2> End of the `avg_bucket` configuration. Comment is not part of the example. The request returns the following response: