From 0376a75c188556c246a3e26cd603ab0f6783fb66 Mon Sep 17 00:00:00 2001 From: Igor Motov Date: Mon, 20 Jul 2020 09:54:02 -0400 Subject: [PATCH] Add hard_bounds documentation (#59809) Fixes #59774 --- .../autodatehistogram-aggregation.asciidoc | 30 ++++++++--------- .../bucket/datehistogram-aggregation.asciidoc | 14 ++++---- .../bucket/histogram-aggregation.asciidoc | 32 +++++++++++++++++++ 3 files changed, 55 insertions(+), 21 deletions(-) diff --git a/docs/reference/aggregations/bucket/autodatehistogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/autodatehistogram-aggregation.asciidoc index 8da1000dc2d47..094afe030a420 100644 --- a/docs/reference/aggregations/bucket/autodatehistogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/autodatehistogram-aggregation.asciidoc @@ -1,7 +1,7 @@ [[search-aggregations-bucket-autodatehistogram-aggregation]] === Auto-interval Date Histogram Aggregation -A multi-bucket aggregation similar to the <> except +A multi-bucket aggregation similar to the <> 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. @@ -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] @@ -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 @@ -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] @@ -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] @@ -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 <>, 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 <>, 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 diff --git a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc index 6003cbb08e786..87a25672d5f18 100644 --- a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc @@ -3,7 +3,7 @@ This multi-bucket aggregation is similar to the normal <>, 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 @@ -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 @@ -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 -<>. +itself, and `hard_bounds` that limits the histogram to specified bounds. +For more information, see +<> and +<>. ===== Missing value @@ -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: diff --git a/docs/reference/aggregations/bucket/histogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/histogram-aggregation.asciidoc index 5de8332f5a458..4b35c495089dc 100644 --- a/docs/reference/aggregations/bucket/histogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/histogram-aggregation.asciidoc @@ -188,6 +188,38 @@ aggregation buckets those documents without regard to how they were selected. See <> 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 <> 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