1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
[[search-facets-date-histogram-facet]]
=== Date Histogram Facet
A specific histogram facet that can work with `date` field types
enhancing it over the regular
<<search-facets-histogram-facet,histogram
facet>>. Here is a quick example:
[source,js]
--------------------------------------------------
{
"query" : {
"match_all" : {}
},
"facets" : {
"histo1" : {
"date_histogram" : {
"field" : "field_name",
"interval" : "day"
}
}
}
}
--------------------------------------------------
==== Interval
The `interval` allows to set the interval at which buckets will be
created for each hit. It allows for the constant values of `year`,
`quarter`, `month`, `week`, `day`, `hour`, `minute`.
It also support time setting like `1.5h` (up to `w` for weeks).
==== Time Zone
By default, times are stored as UTC milliseconds since the epoch. Thus,
all computation and "bucketing" / "rounding" is done on UTC. It is
possible to provide a time zone (both pre rounding, and post rounding)
value, which will cause all computations to take the relevant zone into
account. The time returned for each bucket/entry is milliseconds since
the epoch of the provided time zone.
The parameters are `pre_zone` (pre rounding based on interval) and
`post_zone` (post rounding based on interval). The `time_zone` parameter
simply sets the `pre_zone` parameter. By default, those are set to
`UTC`.
The zone value accepts either a numeric value for the hours offset, for
example: `"time_zone" : -2`. It also accepts a format of hours and
minutes, like `"time_zone" : "-02:30"`. Another option is to provide a
time zone accepted as one of the values listed
http://joda-time.sourceforge.net/timezones.html[here].
Lets take an example. For `2012-04-01T04:15:30Z`, with a `pre_zone` of
`-08:00`. For `day` interval, the actual time by applying the time zone
and rounding falls under `2012-03-31`, so the returned value will be (in
millis) of `2012-03-31T00:00:00Z` (UTC). For `hour` interval, applying
the time zone results in `2012-03-31T20:15:30`, rounding it results in
`2012-03-31T20:00:00`, but, we want to return it in UTC (`post_zone` is
not set), so we convert it back to UTC: `2012-04-01T04:00:00Z`. Note, we
are consistent in the results, returning the rounded value in UTC.
`post_zone` simply takes the result, and adds the relevant offset.
Sometimes, we want to apply the same conversion to UTC we did above for
`hour` also for `day` (and up) intervals. We can set
`pre_zone_adjust_large_interval` to `true`, which will apply the same
conversion done for `hour` interval in the example, to `day` and above
intervals (it can be set regardless of the interval, but only kick in
when using `day` and higher intervals).
==== Factor
The date histogram works on numeric values (since time is stored in
milliseconds since the epoch in UTC). But, sometimes, systems will store
a different resolution (like seconds since UTC) in a numeric field. The
`factor` parameter can be used to change the value in the field to
milliseconds to actual do the relevant rounding, and then be applied
again to get to the original unit. For example, when storing in a
numeric field seconds resolution, the `factor` can be set to `1000`.
==== Pre / Post Offset
Specific offsets can be provided for pre rounding and post rounding. The
`pre_offset` for pre rounding, and `post_offset` for post rounding. The
format is the date time format (`1h`, `1d`, ...).
==== Value Field
The date_histogram facet allows to use a different key (of type date)
which controls the bucketing, with a different value field which will
then return the total and mean for that field values of the hits within
the relevant bucket. For example:
[source,js]
--------------------------------------------------
{
"query" : {
"match_all" : {}
},
"facets" : {
"histo1" : {
"date_histogram" : {
"key_field" : "timestamp",
"value_field" : "price",
"interval" : "day"
}
}
}
}
--------------------------------------------------
==== Script Value Field
A script can be used to compute the value that will then be used to
compute the total and mean for a bucket. For example:
[source,js]
--------------------------------------------------
{
"query" : {
"match_all" : {}
},
"facets" : {
"histo1" : {
"date_histogram" : {
"key_field" : "timestamp",
"value_script" : "doc['price'].value * 2",
"interval" : "day"
}
}
}
}
--------------------------------------------------
|
