date_range 聚合 | ElasticSearch 7.7 权威指南中文版

原英文版地址: https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-aggregations-bucket-daterange-aggregation.html, 原文档版权归 www.elastic.co 所有
本地英文版地址: ../en/search-aggregations-bucket-daterange-aggregation.html

重要: 此版本不会发布额外的bug修复或文档更新。最新信息请参考当前版本文档。

» » »

« date_histogram 聚合 diversified_sampler 聚合 »

日期范围(date_range)聚合

一个专用于日期值的范围(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个月，向下舍入到月初

在上面的示例中，我们创建了两个范围桶，第一个将“存储”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 映射来指定每个字段的默认值来实现的。

POST /sales/_search?size=0
{
   "aggs": {
       "range": {
           "date_range": {
               "field": "date",
               "missing": "1976/11/30",
               "ranges": [
                  {
                    "key": "Older",
                    "to": "2016/02/01"
                  }, 
                  {
                    "key": "Newer",
                    "from": "2016/02/01",
                    "to" : "now/d"
                  }
              ]
          }
      }
   }
}

在 date 字段中没有值的文档将被添加到"Older"桶中，就好像它们的日期值为“1976-11-30”一样。

日期格式/模式

此信息是从日期时间格式化复制的

所有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时区中舍入到一天的开始，可以执行以下操作：

POST /sales/_search?size=0
{
   "aggs": {
       "range": {
           "date_range": {
               "field": "date",
               "time_zone": "CET",
               "ranges": [
                  { "to": "2016/02/01" }, 
                  { "from": "2016/02/01", "to" : "now/d" }, 
                  { "from": "now/d" }
              ]
          }
      }
   }
}

	此日期将被转换为`2016-02-01T00:00:00.000+01:00`。
	`now/d` 将被舍入到CET时区中一天的开始。

keyed 响应

将 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
                }
            }
        }
    }
}

« date_histogram 聚合 diversified_sampler 聚合 »