Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Reformat avg bucket agg reference #69751

Merged
merged 6 commits into from
Mar 2, 2021
Merged

[DOCS] Reformat avg bucket agg reference #69751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
16a31df
[DOCS] Reformat avg bucket agg reference
jrodewig Mar 1, 2021
105e3b1
Reuse syntax block
jrodewig Mar 2, 2021
ee06c0d
Remove unneeded subs customization
jrodewig Mar 2, 2021
deb1334
Add callouts for tag comments
jrodewig Mar 2, 2021
e67a10f
Reword callout
jrodewig Mar 2, 2021
2e7591a
Reword callout
jrodewig Mar 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/Versions.asciidoc
View file
Open in desktop
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
Open in desktop
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think its probably helpful to spend the extra lines to turn this into a CONSOLE example. We'll get the test from it and readers will know where the agg sits in the request tree.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking again, it really is a lot of lines. And we already say we'll have an example below. So I'm not really sure. I do like full examples, but this one would take up the whole screen......

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback @nik9000. I considered either converting this to a full example OR simply moving the example below up. However, it can be difficult to spot where exactly the avg_bucket agg begins/ends. We can do callouts, but that requires a bit more parsing on the part of the reader. I imagine that'll be a problem for most of our pipeline aggs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is like you say, yikes. Do you think we could have the syntax block include a tagged region from the example below? That way at least it won't drift.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a great idea! I implemented this with 105e3b1 (and some cleanup with ee06c0d).

The tagged region comments are now visible in the example. I don't think there is a substitution combo that lets you get rid of them. However, I don't think that's necessarily a bad thing. It does a good job of calling out the agg configuration in context.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth adding callouts for the tagged regions? Just something to explain to the users that the tags indicate the agg configuration but aren't actually part of the example.


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