# 日期范围聚合(Date Range Aggregation)
用于日期值的范围聚合。此聚合和正常[range](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-range-aggregation.html)(范围)聚合的主要区别在于可以用[Date Math](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math)（日期数学）表达式来表示from和to的值，并且还可以指定返回 from 和 to 响应字段的日期格式。注意，此聚合包含 from 值，但是不包含 to 值。
例子：
```
POST /sales/_search?size=0
{
"aggs": {
"range": {
"date_range": {
"field": "date",
"format": "MM-yyy",
"ranges": [
{ "to": "now-10M/M" }, ＃1
{ "from": "now-10M/M" } ＃2
]
}
}
}
}
```
＃1 <现在减去10个月，向下舍入到月初
＃2 >=现在减去10个月，向下舍入到月初
上面的例子，我们创建了两个范围buckets(区间)，第一个将“bucket”的所有文件在10个月前，而第二个将“bucket”所有的文件都是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-*"
}
]
}
}
}
```
## Date Format/Pattern （日期格式）
> 这些信息是从[JodaDate](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)复制过来的
所有ASCII字母都保留为格式模式字母，定义如下:
| 符号 | 含义 | Presentation | 范例 |
| -- | ---------------------------- | ------------ | ------------- |
| G | era | text | AD |
| C | century of era (>=0) | number | 20 |
| Y | year of era (>=0) | year | 1996 |
| x | weekyear | year | 1996 |
| w | week of weekyear | number | 27 |
| e | day of week | number | 2 |
| E | day of week | text | Tuesday; Tue |
| y | year | year | 1996 |
| D | day of year | number | 189 |
| M | month of year | month | July; Jul; 07 |
| d | day of month | number | 10 |
| a | halfday of day | text | PM |
| K | hour of halfday (0\~11) | number | 0 |
| h | clockhour of halfday (1\~12) | number | 12 |
| H | hour of day (0\~23) | number | 0 |
| k | clockhour of day (1\~24) | number | 24 |
| m | minute of hour | number | 30 |
| s | second of minute | number | 55 |
| S | fraction of second | number | 978 |
| z | time zone | text | Pacific Standard Time; PST |
| - | ------------------- | --------- | ----------------------------------- |
| Z | time zone offset/id | zone | -0800; -08:00; America/Los\_Angeles |
| ' | escape for text | delimiter | '' |
模式字母的数量决定了格式
Text
如果模式字母的数量是4或更多，则使用完整的形式，否则，如果有的话，使用简短或缩写形式。
Number
```
最小位数 ，如果不足用0填充
```
Year
```
特别处理年，年的数字表示。 例如，如果y的计数为2，则该年份将显示为本世纪的零年，这是两位数。
```
Month
```
3或以上，使用文字，否则使用数字
```
Zone
```
Z输出无冒号的偏移量，ZZ以冒号输出偏移量，ZZZ或更大输出区域ID。
```
Zone names
```
时区名称（z）无法解析。
```
任何不在\[a..z]和\[A..Z]范围内的字符都将被视为引用的文本。 例如，像：，。，'，'＃和？ 即使它们不包含在单引号内，也会出现在生成的时间文本中。
## Time zone in date range aggregations（日期范围聚合中的时区）
可以通过指定time\_zone参数将日期从另一个时区转换为UTC。
时区可以被指定为ISO 8601 UTC偏移量（例如+01：00或-08：00），也可以指定为TZ数据库的时区ID之一。
time\_zone参数也适用于日期数学表达式中的舍入。 例如，要在CET时区开始一天的开始，您可以执行以下操作：
```
POST /sales/_search?size=0
{
"aggs": {
"range": {
"date_range": {
"field": "date",
"time_zone": "CET",
"ranges": [
{ "to": "2016/02/01" }, ＃1
{ "from": "2016/02/01", "to" : "now/d" ＃2},
{ "from": "now/d" }
]
}
}
}
}
```
＃1 这个日期将改为2016-02-15t00:00 + 01:00
＃2 now/d 将在CET时区四舍五入到一天的开始
## Keyed Response
将 keyed 标志设置为 true ，会将唯一的key与每个bucket关联起来，并将范围作为散列而不是数组返回
```
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
}
}
}
}
}
```
也可以为每个区间自定义key
```
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
}
}
}
}
}
```