Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[DOCS] Reformat avg bucket agg reference
Browse files Browse the repository at this point in the history
jrodewig committed Mar 2, 2021
1 parent d6aa939 commit 16a31df
Showing 2 changed files with 93 additions and 68 deletions.
3 changes: 2 additions & 1 deletion docs/Versions.asciidoc
Original file line number Diff line number Diff line change
@@ -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"]
158 changes: 91 additions & 67 deletions docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc
Original file line number Diff line number Diff line change
@@ -1,44 +1,67 @@
[[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"
"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 <<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`:
==== 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]
--------------------------------------------------
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/]

0 comments on commit 16a31df

Please sign in to comment.