Skip to content

Commit

Permalink
[DOCS] Reformat avg bucket agg reference (elastic#69751) (elastic#69830)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrodewig
jrodewig authored Mar 2, 2021
1 parent f069cf9 commit d495b49
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 76 deletions.
3 changes: 2 additions & 1 deletion docs/Versions.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
171 changes: 96 additions & 75 deletions docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,61 @@
[[search-aggregations-pipeline-avg-bucket-aggregation]]
=== Avg bucket aggregation
=== Average bucket aggregation
++++
<titleabbrev>Avg bucket</titleabbrev>
<titleabbrev>Average bucket</titleabbrev>
++++

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"
}
}
--------------------------------------------------
[source,js,indent=0]
----
include::avg-bucket-aggregation.asciidoc[tag=avg-bucket-agg-syntax]
----
// 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 <<buckets-path-syntax>> for more
details) |Required |
|`gap_policy` |The policy to apply when gaps are found in the data (see <<gap-policy>> 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`:

[source,console]
--------------------------------------------------
POST /_search
==== Parameters

`buckets_path`::
(Required, string)
Path to the buckets to average. For syntax, see <<buckets-path-syntax>>.

`gap_policy`::
(Optional, string)
Policy to apply when gaps are found in the data. For valid values, see
<<buckets-path-syntax>>. 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,subs="specialchars+"]
----
POST _search
{
"size": 0,
"aggs": {
Expand All @@ -56,63 +73,67 @@ POST /_search
}
},
"avg_monthly_sales": {
// tag::avg-bucket-agg-syntax[] <1>
"avg_bucket": {
"buckets_path": "sales_per_month>sales" <1>
"buckets_path": "sales_per_month>sales",
"gap_policy": "skip",
"format": "#,##0.00;(#,##0.00)"
}
// end::avg-bucket-agg-syntax[] <2>
}
}
}
--------------------------------------------------
----
// TEST[setup:sales]

<1> `buckets_path` instructs this avg_bucket aggregation that we want the (mean) average value of the `sales` aggregation in the
`sales_per_month` date histogram.
<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.

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/]

0 comments on commit d495b49

Please sign in to comment.