Skip to content

Commit d495b49

Browse files
jrodewigjrodewig
authored
[DOCS] Reformat avg bucket agg reference (#69751) (#69830)
1 parent f069cf9 commit d495b49

File tree

2 files changed

+98
-76
lines changed

2 files changed

+98
-76
lines changed

‎docs/Versions.asciidoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,8 @@ include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
1515
///////
1616
Javadoc roots used to generate links from Painless's API reference
1717
///////
18-
:java11-javadoc: https://docs.oracle.com/en/java/javase/11/docs/api
18+
:javadoc: https://docs.oracle.com/en/java/javase/{jdk_major}/docs/api
19+
:java11-javadoc: https://docs.oracle.com/en/java/javase/11/docs/api
1920
:lucene-core-javadoc: https://lucene.apache.org/core/{lucene_version_path}/core
2021

2122
ifeval::["{release-state}"=="unreleased"]

‎docs/reference/aggregations/pipeline/avg-bucket-aggregation.asciidoc‎

Lines changed: 96 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,61 @@
11
[[search-aggregations-pipeline-avg-bucket-aggregation]]
2-
=== Avg bucket aggregation
2+
=== Average bucket aggregation
33
++++
4-
<titleabbrev>Avg bucket</titleabbrev>
4+
<titleabbrev>Average bucket</titleabbrev>
55
++++
66

7-
A sibling pipeline aggregation which calculates the (mean) average value of a specified metric in a sibling aggregation.
8-
The specified metric must be numeric and the sibling aggregation must be a multi-bucket aggregation.
7+
A sibling pipeline aggregation which calculates the mean value of a specified
8+
metric in a sibling aggregation. The specified metric must be numeric and the
9+
sibling aggregation must be a multi-bucket aggregation.
910

1011
[[avg-bucket-agg-syntax]]
1112
==== Syntax
1213

13-
An `avg_bucket` aggregation looks like this in isolation:
14-
15-
[source,js]
16-
--------------------------------------------------
17-
{
18-
"avg_bucket": {
19-
"buckets_path": "the_sum"
20-
}
21-
}
22-
--------------------------------------------------
14+
[source,js,indent=0]
15+
----
16+
include::avg-bucket-aggregation.asciidoc[tag=avg-bucket-agg-syntax]
17+
----
2318
// NOTCONSOLE
2419

2520
[[avg-bucket-params]]
26-
.`avg_bucket` Parameters
27-
[options="header"]
28-
|===
29-
|Parameter Name |Description |Required |Default Value
30-
|`buckets_path` |The path to the buckets we wish to find the average for (see <<buckets-path-syntax>> for more
31-
details) |Required |
32-
|`gap_policy` |The policy to apply when gaps are found in the data (see <<gap-policy>> for more
33-
details) |Optional |`skip`
34-
|`format` |format to apply to the output value of this aggregation |Optional | `null`
35-
|===
36-
37-
The following snippet calculates the average of the total monthly `sales`:
38-
39-
[source,console]
40-
--------------------------------------------------
41-
POST /_search
21+
==== Parameters
22+
23+
`buckets_path`::
24+
(Required, string)
25+
Path to the buckets to average. For syntax, see <<buckets-path-syntax>>.
26+
27+
`gap_policy`::
28+
(Optional, string)
29+
Policy to apply when gaps are found in the data. For valid values, see
30+
<<buckets-path-syntax>>. Defaults to `skip`.
31+
32+
`format`::
33+
(Optional, string)
34+
{javadoc}/java.base/java/text/DecimalFormat.html[DecimalFormat pattern] for the
35+
output value. If specified, the formatted value is returned in the aggregation's
36+
`value_as_string` property.
37+
38+
[[avg-bucket-agg-response]]
39+
==== Response body
40+
41+
`value`::
42+
(float)
43+
Mean average value for the metric specified in `buckets_path`.
44+
45+
`value_as_string`::
46+
(string)
47+
Formatted output value for the aggregation. This property is only provided if
48+
a `format` is specified in the request.
49+
50+
[[avg-bucket-agg-ex]]
51+
==== Example
52+
53+
The following `avg_monthly_sales` aggregation uses `avg_bucket` to calculate
54+
average sales per month:
55+
56+
[source,console,subs="specialchars+"]
57+
----
58+
POST _search
4259
{
4360
"size": 0,
4461
"aggs": {
@@ -56,63 +73,67 @@ POST /_search
5673
}
5774
},
5875
"avg_monthly_sales": {
76+
// tag::avg-bucket-agg-syntax[] <1>
5977
"avg_bucket": {
60-
"buckets_path": "sales_per_month>sales" <1>
78+
"buckets_path": "sales_per_month>sales",
79+
"gap_policy": "skip",
80+
"format": "#,##0.00;(#,##0.00)"
6181
}
82+
// end::avg-bucket-agg-syntax[] <2>
6283
}
6384
}
6485
}
65-
66-
--------------------------------------------------
86+
----
6787
// TEST[setup:sales]
6888

69-
<1> `buckets_path` instructs this avg_bucket aggregation that we want the (mean) average value of the `sales` aggregation in the
70-
`sales_per_month` date histogram.
89+
<1> Start of the `avg_bucket` configuration. Comment is not part of the example.
90+
<2> End of the `avg_bucket` configuration. Comment is not part of the example.
7191

72-
And the following may be the response:
92+
The request returns the following response:
7393

7494
[source,console-result]
75-
--------------------------------------------------
95+
----
7696
{
77-
"took": 11,
78-
"timed_out": false,
79-
"_shards": ...,
80-
"hits": ...,
81-
"aggregations": {
82-
"sales_per_month": {
83-
"buckets": [
84-
{
85-
"key_as_string": "2015/01/01 00:00:00",
86-
"key": 1420070400000,
87-
"doc_count": 3,
88-
"sales": {
89-
"value": 550.0
90-
}
91-
},
92-
{
93-
"key_as_string": "2015/02/01 00:00:00",
94-
"key": 1422748800000,
95-
"doc_count": 2,
96-
"sales": {
97-
"value": 60.0
98-
}
99-
},
100-
{
101-
"key_as_string": "2015/03/01 00:00:00",
102-
"key": 1425168000000,
103-
"doc_count": 2,
104-
"sales": {
105-
"value": 375.0
106-
}
107-
}
108-
]
109-
},
110-
"avg_monthly_sales": {
111-
"value": 328.33333333333333
112-
}
113-
}
97+
"took": 11,
98+
"timed_out": false,
99+
"_shards": ...,
100+
"hits": ...,
101+
"aggregations": {
102+
"sales_per_month": {
103+
"buckets": [
104+
{
105+
"key_as_string": "2015/01/01 00:00:00",
106+
"key": 1420070400000,
107+
"doc_count": 3,
108+
"sales": {
109+
"value": 550.0
110+
}
111+
},
112+
{
113+
"key_as_string": "2015/02/01 00:00:00",
114+
"key": 1422748800000,
115+
"doc_count": 2,
116+
"sales": {
117+
"value": 60.0
118+
}
119+
},
120+
{
121+
"key_as_string": "2015/03/01 00:00:00",
122+
"key": 1425168000000,
123+
"doc_count": 2,
124+
"sales": {
125+
"value": 375.0
126+
}
127+
}
128+
]
129+
},
130+
"avg_monthly_sales": {
131+
"value": 328.33333333333333,
132+
"value_as_string": "328.33"
133+
}
134+
}
114135
}
115-
--------------------------------------------------
136+
----
116137
// TESTRESPONSE[s/"took": 11/"took": $body.took/]
117138
// TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]
118139
// TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]

0 commit comments

Comments
 (0)