You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A multi-bucket aggregation similar to the <<search-aggregations-bucket-histogram-aggregation,histogram>> except it can
5
-
only be applied on date values. Since dates are represented in Elasticsearch internally as long values, it is possible
6
-
to use the normal `histogram` on dates as well, though accuracy will be compromised. The reason for this is in the fact
7
-
that time based intervals are not fixed (think of leap years and on the number of days in a month). For this reason,
8
-
we need special support for time based data. From a functionality perspective, this histogram supports the same features
9
-
as the normal <<search-aggregations-bucket-histogram-aggregation,histogram>>. The main difference is that the interval can be specified by date/time expressions.
4
+
This multi-bucket aggregation is similar to the normal
5
+
<<search-aggregations-bucket-histogram-aggregation,histogram>>, but it can
6
+
only be used with date values. Because dates are represented internally in
7
+
Elasticsearch as long values, it is possible, but not as accurate, to use the
8
+
normal `histogram` on dates as well. The main difference in the two APIs is
9
+
that here the interval can be specified using date/time expressions. Time-based
10
+
data requires special support because time-based intervals are not always a
11
+
fixed length.
12
+
13
+
==== Setting intervals
14
+
15
+
There seems to be no limit to the creativity we humans apply to setting our
16
+
clocks and calendars. We've invented leap years and leap seconds, standard and
17
+
daylight savings times, and timezone offsets of 30 or 45 minutes rather than a
18
+
full hour. While these creations help keep us in sync with the cosmos and our
19
+
environment, they can make specifying time intervals accurately a real challenge.
20
+
The only universal truth our researchers have yet to disprove is that a
21
+
millisecond is always the same duration, and a second is always 1000 milliseconds.
22
+
Beyond that, things get complicated.
23
+
24
+
Generally speaking, when you specify a single time unit, such as 1 hour or 1 day, you
25
+
are working with a _calendar interval_, but multiples, such as 6 hours or 3 days, are
26
+
_fixed-length intervals_.
27
+
28
+
For example, a specification of 1 day (1d) from now is a calendar interval that
29
+
means "at
30
+
this exact time tomorrow" no matter the length of the day. A change to or from
31
+
daylight savings time that results in a 23 or 25 hour day is compensated for and the
32
+
specification of "this exact time tomorrow" is maintained. But if you specify 2 or
33
+
more days, each day must be of the same fixed duration (24 hours). In this case, if
34
+
the specified interval includes the change to or from daylight savings time, the
35
+
interval will end an hour sooner or later than you expect.
36
+
37
+
There are similar differences to consider when you specify single versus multiple
38
+
minutes or hours. Multiple time periods longer than a day are not supported.
39
+
40
+
Here are the valid time specifications and their meanings:
41
+
42
+
milliseconds (ms) ::
43
+
Fixed length interval; supports multiples.
44
+
45
+
seconds (s) ::
46
+
1000 milliseconds; fixed length interval (except for the last second of a
47
+
minute that contains a leap-second, which is 2000ms long); supports multiples.
48
+
49
+
minutes (m) ::
50
+
All minutes begin at 00 seconds.
51
+
52
+
* One minute (1m) is the interval between 00 seconds of the first minute and 00
53
+
seconds of the following minute in the specified timezone, compensating for any
54
+
intervening leap seconds, so that the number of minutes and seconds past the
55
+
hour is the same at the start and end.
56
+
* Multiple minutes (__n__m) are intervals of exactly 60x1000=60,000 milliseconds
57
+
each.
58
+
59
+
hours (h) ::
60
+
All hours begin at 00 minutes and 00 seconds.
61
+
62
+
* One hour (1h) is the interval between 00:00 minutes of the first hour and 00:00
63
+
minutes of the following hour in the specified timezone, compensating for any
64
+
intervening leap seconds, so that the number of minutes and seconds past the hour
65
+
is the same at the start and end.
66
+
* Multiple hours (__n__h) are intervals of exactly 60x60x1000=3,600,000 milliseconds
67
+
each.
68
+
69
+
days (d) ::
70
+
All days begin at the earliest possible time, which is usually 00:00:00
71
+
(midnight).
72
+
73
+
* One day (1d) is the interval between the start of the day and the start of
74
+
of the following day in the specified timezone, compensating for any intervening
75
+
time changes.
76
+
* Multiple days (__n__d) are intervals of exactly 24x60x60x1000=86,400,000
77
+
milliseconds each.
78
+
79
+
weeks (w) ::
80
+
81
+
* One week (1w) is the interval between the start day_of_week:hour:minute:second
82
+
and the same day of the week and time of the following week in the specified
83
+
timezone.
84
+
* Multiple weeks (__n__w) are not supported.
85
+
86
+
months (M) ::
87
+
88
+
* One month (1M) is the interval between the start day of the month and time of
89
+
day and the same day of the month and time of the following month in the specified
90
+
timezone, so that the day of the month and time of day are the same at the start
91
+
and end.
92
+
* Multiple months (__n__M) are not supported.
93
+
94
+
quarters (q) ::
95
+
96
+
* One quarter (1q) is the interval between the start day of the month and
97
+
time of day and the same day of the month and time of day three months later,
98
+
so that the day of the month and time of day are the same at the start and end. +
99
+
* Multiple quarters (__n__q) are not supported.
100
+
101
+
years (y) ::
102
+
103
+
* One year (1y) is the interval between the start day of the month and time of
104
+
day and the same day of the month and time of day the following year in the
105
+
specified timezone, so that the date and time are the same at the start and end. +
106
+
* Multiple years (__n__y) are not supported.
107
+
108
+
NOTE:
109
+
In all cases, when the specified end time does not exist, the actual end time is
110
+
the closest available time after the specified end.
111
+
112
+
Widely distributed applications must also consider vagaries such as countries that
113
+
start and stop daylight savings time at 12:01 A.M., so end up with one minute of
114
+
Sunday followed by an additional 59 minutes of Saturday once a year, and countries
115
+
that decide to move across the international date line. Situations like
116
+
that can make irregular timezone offsets seem easy.
117
+
118
+
As always, rigorous testing, especially around time-change events, will ensure
119
+
that your time interval specification is
120
+
what you intend it to be.
121
+
122
+
WARNING:
123
+
To avoid unexpected results, all connected servers and clients must sync to a
124
+
reliable network time service.
125
+
126
+
==== Examples
10
127
11
128
Requesting bucket intervals of a month.
12
129
@@ -27,13 +144,11 @@ POST /sales/_search?size=0
27
144
// CONSOLE
28
145
// TEST[setup:sales]
29
146
30
-
Available expressions for interval: `year` (`1y`), `quarter` (`1q`), `month` (`1M`), `week` (`1w`),
0 commit comments