本地英文版地址: ../en/search-aggregations-bucket-daterange-aggregation.html
一个专用于日期值的范围(range)聚合。
这种聚合与普通范围(range)聚合的主要区别在于，from 和 to 的值可以用日期计算(Date Math)表达式表示，并且还可以指定返回的 from 和 to 响应字段的日期格式。
请注意，此聚合包括每个范围的 from的值，但不包括 to的值。左闭右开区间，即: [from, to)
示例：
POST /sales/_search?size=0
{
"aggs": {
"range": {
"date_range": {
"field": "date",
"format": "MM-yyyy",
"ranges": [
{ "to": "now-10M/M" },
{ "from": "now-10M/M" }
]
}
}
}
}
在上面的示例中，我们创建了两个范围桶，第一个将“存储”10个月之前的所有文档，第二个将“存储”10个月之后的所有文档
响应：
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
参数 missing 定义了如何处理缺少值的文档。
默认情况下，它们被忽略，但是也可以将它们视为有一个值。
这是通过添加一组 fieldname : value 映射来指定每个字段的默认值来实现的。
此信息是从日期时间格式化复制的
所有ASCII字母都保留为格式模式字母，定义如下：
| 符号 | 含义 | 表现形式 | 示例 |
|---|---|---|---|
G |
纪元 |
text |
AD; Anno Domini; A |
u |
年份 |
year |
2004; 04 |
y |
纪元中的第几年 |
year |
2004; 04 |
D |
一年中的第几天 |
number |
189 |
M/L |
(第几个)月 |
number/text |
7; 07; Jul; July; J |
d |
一个月中的第几天 |
number |
10 |
Q/q |
(第几个)季度 |
number/text |
3; 03; Q3; 3rd quarter |
Y |
week-based-year |
year |
1996; 96 |
w |
week-of-week-based-year |
number |
27 |
W |
一个月的第几周 |
number |
4 |
E |
星期几 |
text |
Tue; Tuesday; T |
e/c |
本地化的星期几 |
number/text |
2; 02; Tue; Tuesday; T |
F |
一个月的第几周 |
number |
3 |
a |
上午/下午 |
text |
AM; PM |
h |
12小时制的钟点(1-12) |
number |
12 |
K |
12小时制的小时 (0-11) |
number |
0 |
k |
24小时制的钟点 (1-24) |
number |
0 |
H |
一天的小时 (0-23) |
number |
0 |
m |
分钟 |
number |
30 |
s |
秒 |
number |
55 |
S |
毫秒 |
fraction |
978 |
A |
milli-of-day |
number |
1234 |
n |
纳秒 |
number |
987654321 |
N |
一天的第几纳秒 |
number |
1234000000 |
V |
时区ID |
zone-id |
America/Los_Angeles; Z; -08:30 |
z |
时区的名字 |
zone-name |
Pacific Standard Time; PST |
O |
本地化的时区偏移 |
offset-O |
GMT+8; GMT+08:00; UTC-08:00; |
X |
Z基于0的时区偏移 |
offset-X |
Z; -08; -0830; -08:30; -083015; -08:30:15; |
x |
时区偏移 |
offset-x |
+0000; -08; -0830; -08:30; -083015; -08:30:15; |
Z |
时区偏移 |
offset-Z |
+0000; -0800; -08:00; |
p |
下一填充 |
pad modifier |
1 |
' |
文本转义 |
delimiter |
'' |
' |
单引号 |
literal |
' |
[ |
可选部分开始 |
||
] |
可选部分结束 |
||
# |
留作将来使用 |
||
{ |
留作将来使用 |
||
} |
留作将来使用 |
模式字母的数量决定了格式。
- Text
-
文本样式是由使用的模式字母的数量确定的。
少于4个模式字母将使用短格式，正好4个模式字母将使用完整的形式，正好5个字母将使用窄格式。
模式字母
L、c及q指定文本样式的独立形式。 - Number
-
如果模式字母的数量为1，则使用最少的位数输出该值，且不进行填充。
否则，使用数字的数量作为输出字段的宽度，必要时用零填充。
以下模式字母对字母的数量有限制。
c和F只能指定一个字母。d、H、h、K、k、m及s最多可以指定2个字母。D最多可以指定3个字母。 - Number/Text
- 如果模式字母的数量为3或更多时，使用上面的 Text 规则，否则使用上面的 Number 规则。
- Fraction
- 以秒的小数形式输出纳秒字段。 纳秒值有九个数字，因此模式字母的数量是从1到9。 如果小于9，则纳秒值被截断，只输出最高有效位。
- Year
-
字母的数量决定了最小字段宽度，在该宽度以下使用填充。
如果字母的数量是2，则使用简化的两位数形式。
解析时，将使用基数2000进行解析，得到2000到2099(含)范围内的年份。
如果字母的数量小于4(但也不是2)，那么根据
SignStyle.NORMAL，只输出负年份的符号。 否则，如果超出填充宽度，根据SignStyle.EXCEEDS_PAD，输出符号。 - ZoneId
-
输出时区ID，例如
Europe/Paris。 如果字母的数量为2，则输出时区ID。 任何其他字母的数量都会抛出IllegalArgumentException异常。 - Zone names
-
这将输出时区ID的显示名称。
如果字母数是一、二或三，则输出简称；如果字母数为4，则输出全名；五个或更多字母抛出
IllegalArgumentException异常。 - Offset X 和 x
-
这将根据模式字母的数量格式化 offset。
一个字母只输出小时，如
+01，除非分钟是非零的，在这种情况下，分钟也输出，如+0130。 两个字母输出小时和分钟，不带冒号，如+0130。 三个字母输出小时和分钟，带冒号，如+01:30。 四个字母输出小时、分钟和可选的秒，不带冒号，例如+013015。 五个字母输出小时、分钟和可选的秒，带冒号，如+01:30:15。 六个或更多的字母则抛出IllegalArgumentException异常。 当要输出的偏移为零时，模式字母X(大写)将输出Z，而模式字母x(小写)将输出+00、+0000或+00:00。 - Offset O
-
这将根据模式字母的数量格式化本地化的offset。
一个字母输出本地化offset的简短形式，它是本地化的offset的文本，如
GMT，包括不带前导零的小时、可选的2位数分钟和秒(如果非零)以及冒号，如GMT+8。 四个字母输出完整的形式，这是本地化的offset的文本，如GMT，具有两位数的小时和分钟字段，非零时的可选的第二个字段，以及冒号，例如GMT+08:00。 任何其他字母计数都会抛出IllegalArgumentException异常。 - Offset Z
-
这将根据模式字母的数量格式化offset。
一个、两个或三个字母输出小时和分钟，不带冒号，如
+0130。 当offset为零时，输出将为+0000。 四个字母输出本地化offset的完整形式，相当于Offset-O的四个字母。 如果offset为零，输出将是相应的本地化offset文本。 五个字母输出小时、分钟，如果非零，可选秒，带冒号。 如果offset为零，则输出Z。 六个或更多字母抛出IllegalArgumentException异常。 - 可选(optional)部分
-
可选部分标记的工作方式与调用
DateTimeFormatterBuilder.optionalStart()和DateTimeFormatterBuilder.optionalEnd()完全一样。 - 填充修饰符
-
将紧随其后的模式修改为用空格填充。
填充宽度由模式字母的数量决定。
这与调用
DateTimeFormatterBuilder.padNext(int)相同。
例如，ppH输出在左边用空格填充宽度为2的的一天中的小时。
任何无法识别的字母都是错误的。
除[、]、{、}、#和单引号之外的任何非字母字符将被直接输出。
尽管如此，还是建议在所有想要直接输出的字符周围使用单引号，以确保将来的更改不会破坏应用程序。
通过指定 time_zone 参数，可以将日期从另一个时区转换为UTC。
时区可以指定为ISO 8601 UTC时差(例如+01:00或-08:00)，也可以指定为TZ数据库中的时区id之一。
参数 time_zone 也适用于日期数学表达式中的舍入。
例如，要在CET时区中舍入到一天的开始，可以执行以下操作：
将 keyed 标志设置为 true会将唯一的字符串键与每个桶相关联，并将范围作为哈希而不是数组返回：
POST /sales/_search?size=0
{
"aggs": {
"range": {
"date_range": {
"field": "date",
"format": "MM-yyy",
"ranges": [
{ "to": "now-10M/M" },
{ "from": "now-10M/M" }
],
"keyed": true
}
}
}
}
响应：
{
...
"aggregations": {
"range": {
"buckets": {
"*-10-2015": {
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7
},
"10-2015-*": {
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0
}
}
}
}
}
也可以为每个范围定制一个键：
POST /sales/_search?size=0
{
"aggs": {
"range": {
"date_range": {
"field": "date",
"format": "MM-yyy",
"ranges": [
{ "from": "01-2015", "to": "03-2015", "key": "quarter_01" },
{ "from": "03-2015", "to": "06-2015", "key": "quarter_02" }
],
"keyed": true
}
}
}
}
响应：
{
...
"aggregations": {
"range": {
"buckets": {
"quarter_01": {
"from": 1.4200704E12,
"from_as_string": "01-2015",
"to": 1.425168E12,
"to_as_string": "03-2015",
"doc_count": 5
},
"quarter_02": {
"from": 1.425168E12,
"from_as_string": "03-2015",
"to": 1.4331168E12,
"to_as_string": "06-2015",
"doc_count": 2
}
}
}
}
}