# 日期范围聚合(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
}
}
}
}
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://xiaoxiami.gitbook.io/elasticsearch/ji-chu/36aggregationsju-he-fen-679029/362tong-ju540828-bucketaggregations/date-range-aggregation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.