Skip to content

[7.x] Add hard_bounds documentation (#59809) #59883

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

Merged
merged 1 commit into from
Jul 20, 2020
Merged

[7.x] Add hard_bounds documentation (#59809) #59883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
30 changes: 15 additions & 15 deletions docs/reference/aggregations/bucket/autodatehistogram-aggregation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[search-aggregations-bucket-autodatehistogram-aggregation]]
=== Auto-interval Date Histogram Aggregation

A multi-bucket aggregation similar to the <<search-aggregations-bucket-datehistogram-aggregation>> except
A multi-bucket aggregation similar to the <<search-aggregations-bucket-datehistogram-aggregation>> except
instead of providing an interval to use as the width of each bucket, a target number of buckets is provided
indicating the number of buckets needed and the interval of the buckets is automatically chosen to best achieve
that target. The number of buckets returned will always be less than or equal to this target number.
Expand Down Expand Up @@ -89,8 +89,8 @@ Response:

==== Intervals

The interval of the returned buckets is selected based on the data collected by the
aggregation so that the number of buckets returned is less than or equal to the number
The interval of the returned buckets is selected based on the data collected by the
aggregation so that the number of buckets returned is less than or equal to the number
requested. The possible intervals returned are:

[horizontal]
Expand All @@ -101,8 +101,8 @@ days:: In multiples of 1, and 7
months:: In multiples of 1, and 3
years:: In multiples of 1, 5, 10, 20, 50 and 100

In the worst case, where the number of daily buckets are too many for the requested
number of buckets, the number of buckets returned will be 1/7th of the number of
In the worst case, where the number of daily buckets are too many for the requested
number of buckets, the number of buckets returned will be 1/7th of the number of
buckets requested.

==== Time Zone
Expand Down Expand Up @@ -147,7 +147,7 @@ GET my_index/_search?size=0
}
---------------------------------

UTC is used if no time zone is specified, three 1-hour buckets are returned
UTC is used if no time zone is specified, three 1-hour buckets are returned
starting at midnight UTC on 1 October 2015:

[source,console-result]
Expand Down Expand Up @@ -201,8 +201,8 @@ GET my_index/_search?size=0
// TEST[continued]


Now three 1-hour buckets are still returned but the first bucket starts at
11:00pm on 30 September 2015 since that is the local time for the bucket in
Now three 1-hour buckets are still returned but the first bucket starts at
11:00pm on 30 September 2015 since that is the local time for the bucket in
the specified time zone.

[source,console-result]
Expand Down Expand Up @@ -242,17 +242,17 @@ WARNING: When using time zones that follow DST (daylight savings time) changes,
buckets close to the moment when those changes happen can have slightly different
sizes than neighbouring buckets.
For example, consider a DST start in the `CET` time zone: on 27 March 2016 at 2am,
clocks were turned forward 1 hour to 3am local time. If the result of the aggregation
was daily buckets, the bucket covering that day will only hold data for 23 hours
instead of the usual 24 hours for other buckets. The same is true for shorter intervals
like e.g. 12h. Here, we will have only a 11h bucket on the morning of 27 March when the
clocks were turned forward 1 hour to 3am local time. If the result of the aggregation
was daily buckets, the bucket covering that day will only hold data for 23 hours
instead of the usual 24 hours for other buckets. The same is true for shorter intervals
like e.g. 12h. Here, we will have only a 11h bucket on the morning of 27 March when the
DST shift happens.

==== Scripts

Like with the normal <<search-aggregations-bucket-datehistogram-aggregation, `date_histogram`>>, both document level
scripts and value level scripts are supported. This aggregation does not however, support the `min_doc_count`,
`extended_bounds` and `order` parameters.
Like with the normal <<search-aggregations-bucket-datehistogram-aggregation, `date_histogram`>>, both document level
scripts and value level scripts are supported. This aggregation does not however, support the `min_doc_count`,
`extended_bounds`, `hard_bounds` and `order` parameters.

==== Minimum Interval parameter

Expand Down
14 changes: 8 additions & 6 deletions docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

This multi-bucket aggregation is similar to the normal
<<search-aggregations-bucket-histogram-aggregation,histogram>>, but it can
only be used with date or date range values. Because dates are represented internally in
only be used with date or date range values. Because dates are represented internally in
Elasticsearch as long values, it is possible, but not as accurate, to use the
normal `histogram` on dates as well. The main difference in the two APIs is
that here the interval can be specified using date/time expressions. Time-based
Expand Down Expand Up @@ -269,10 +269,10 @@ In all cases, when the specified end time does not exist, the actual end time is
the closest available time after the specified end.

Widely distributed applications must also consider vagaries such as countries that
start and stop daylight savings time at 12:01 A.M., so end up with one minute of
start and stop daylight savings time at 12:01 A.M., so end up with one minute of
Sunday followed by an additional 59 minutes of Saturday once a year, and countries
that decide to move across the international date line. Situations like
that can make irregular time zone offsets seem easy.
that can make irregular time zone offsets seem easy.

As always, rigorous testing, especially around time-change events, will ensure
that your time interval specification is
Expand Down Expand Up @@ -623,8 +623,10 @@ settings and filter the returned buckets based on a `min_doc_count` setting
bucket that matches documents and the last one are returned). This histogram
also supports the `extended_bounds`
setting, which enables extending the bounds of the histogram beyond the data
itself. For more information, see
<<search-aggregations-bucket-histogram-aggregation-extended-bounds,`Extended Bounds`>>.
itself, and `hard_bounds` that limits the histogram to specified bounds.
For more information, see
<<search-aggregations-bucket-histogram-aggregation-extended-bounds,`Extended Bounds`>> and
<<search-aggregations-bucket-histogram-aggregation-hard-bounds,`Hard Bounds`>>.

===== Missing value

Expand Down Expand Up @@ -661,7 +663,7 @@ the `order` setting. This setting supports the same `order` functionality as

===== Using a script to aggregate by day of the week

When you need to aggregate the results by day of the week, use a script that
When you need to aggregate the results by day of the week, use a script that
returns the day of the week:


Expand Down
32 changes: 32 additions & 0 deletions docs/reference/aggregations/bucket/histogram-aggregation.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,38 @@ aggregation buckets those documents without regard to how they were selected.
See <<search-aggregations-bucket-range-field-note,note on bucketing range
fields>> for more information and an example.

[[search-aggregations-bucket-histogram-aggregation-hard-bounds]]
The `hard_bounds` is a counterpart of `extended_bounds` and can limit the range of buckets in the histogram. It is
particularly useful in the case of open <<range, data ranges>> that can result in a very large number of buckets.

Example:

[source,console,id=histogram-aggregation-hard-bounds-example]
--------------------------------------------------
POST /sales/_search?size=0
{
"query" : {
"constant_score" : { "filter": { "range" : { "price" : { "to" : "500" } } } }
},
"aggs" : {
"prices" : {
"histogram" : {
"field" : "price",
"interval" : 50,
"hard_bounds" : {
"min" : 100,
"max" : 200
}
}
}
}
}
--------------------------------------------------
// TEST[setup:sales]

In this example even though the range specified in the query is up to 500, the histogram will only have 2 buckets starting at 100 and 150.
All other buckets will be omitted even even if documents that should go to this buckets are present in the results.

==== Order

By default the returned buckets are sorted by their `key` ascending, though the order behaviour can be controlled using
Expand Down