From 62a3ebe7f1575f922794dfce7a3e252c2f6c6475 Mon Sep 17 00:00:00 2001 From: Sue-Gallagher Date: Thu, 5 Jul 2018 08:37:06 -0700 Subject: [PATCH] [DOCS] Add info on calendar v fixed interval. Closes #29410 q! q --- .../bucket/datehistogram-aggregation.asciidoc | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc index e70b4463adae6..d6b84734a2d34 100644 --- a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc @@ -95,7 +95,7 @@ and end. quarters (q) :: -* One quarter (1q) is the interval between the start day of the month and time +* One quarter (1q) is the interval between the start day of the month and time of day and the same day of the month and time of day three months later, so that the day of the month and time of day are the same at the start and end. + * Multiple quarters (__n__q) are not supported. @@ -109,11 +109,12 @@ specified timezone, so that the date and time are the same at the start and 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 -Sunday followed by an additional 59 minutes of Saturday every fall, and countries +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 timezone offsets seem easy. -As always, rigorous testing will ensure that your time interval specification is +As always, rigorous testing, especially around time-change events, will ensure +that your time interval specification is what you intend it to be. WARNING: @@ -167,9 +168,9 @@ POST /sales/_search?size=0 ===== Keys Internally, a date is represented as a 64 bit number representing a timestamp -in milliseconds-since-the-epoch (01/01/1970). These timestamps are returned as -the bucket -++key++s. The `key_as_string` is the same timestamp converted to a formatted +in milliseconds-since-the-epoch (01/01/1970 midnight UTC). These timestamps are +returned as the ++key++ name of the bucket. The `key_as_string` is the same +timestamp converted to a formatted date string using the `format` parameter sprcification: TIP: If you don't specify `format`, the first date @@ -233,8 +234,8 @@ rounding is also done in UTC. Use the `time_zone` parameter to indicate that bucketing should use a different timezone. You can specify timezones as either an ISO 8601 UTC offset (e.g. `+01:00` or -`-08:00`) or as a timezone id, an identifier used in the TZ database like -`America/Los_Angeles`. +`-08:00`) or as a timezone ID as specified in the IANA timezone database, +such as`America/Los_Angeles`. Consider the following example: @@ -287,8 +288,8 @@ on 1 October 2015: --------------------------------- // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/] -If you specify a `time_zone` of `-01:00`, then midnight starts at one hour before -midnight UTC: +If you specify a `time_zone` of `-01:00`, midnight in that timezone is one hour +before midnight UTC: [source,js] ---------------------------------