5.2.6. 日期范围聚合

7.3

7.3

日期范围聚合

日期范围聚合是专用于日期值的范围聚合。该聚合和正常的 范围 聚合的区别主要在于：该聚合可以用 日期数学 表达式表示 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 参数对文档缺少值的情况进行了定义。默认情况下，它们会被忽略，但也可以认为它们有值。可以通过添加一组 字段名：值 的映射来指定每个字段的默认值。

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 字母都保留为格式化模式字母，其定义如下：

模式字母的数量决定了格式。

文本

文本样式由使用的模式字母确定。少于 4 个模式字母将使用缩写格式。恰好 4 个模式字母将使用完整格式。正好 5 个模式字母将使用窄边格式。模式字母 L，c 和 q 指定文本样式的独立格式。

• 数字

如果字母数量为 1，则使用最少的位数输出该值，并且不进行填充。其他情况，则使用数字位数作为输出字母的宽度，并且必要时用 0 进行填充。以下模式字符对字母数量有约束。字母 c 和 F 只能指定一个。字母 d，H，h，K，k，m 和 s 最多可以指定两个。字母 D 最多可以指定三个。

• 数字/文本

如果模式字母的数量是 3 个或者 3 个以上，请使用上面的文本规则。 否则使用上面的数字规则。

• 分数

用纳秒输出几分之一秒。纳秒值有 9 位数，因此模式字母的数量为从 1 到 9，如果模式字母的数量少于 9 个，则纳秒的值将被截断，仅输出最高有效位。

• 年份

字母的数量决定了使用填充的最小字段宽度。如果字母数量为 2，则使用简化的两位数格式。对于打印，则输出最右边的两位数字。对于解析，则使用 2000 的基值进行解析，从而产生 2000 到 2099（包括 2000 和 2099）范围内的一年。如果字母数少于 4 个（但不是 2 个），则按照 SignStyle.NORMAL 符号风格，仅负年数输出符号。其他情况，则按照 SignStyle.EXCEEDS_PAD 符号风格，只输出超出宽度限制的符号。

• 时区ID

输出时区ID，例如 Europe/Paris。如果字母数为 2，则输出时区ID。其他个数则抛出 IllegalArgumentException 异常。

• 时区名称

输出时区ID的展示名称。如果字母的数量为 1，2，或 3，则输出短名称。如果字母数量为 4 个，则输出完整名称。5 个及以上的字母则抛出 IllegalArgumentException 异常。

• 偏移 X 和 x

根据模式字母的数量格式化偏移。一个字母仅输出小时，例如 +01，分钟非零情况下也会被输出，例如 +0130。两个字母输出没有冒号的小时和分钟，例如 +0130。三个字母输出带有冒号的小时和分钟，例如 +01:30。四个字母输出没有冒号的小时、分钟和可选秒，例如 +013015。五个字母输出带有冒号的小时、分钟和可选秒，例如 +01:30:15。留个字母会抛出 IllegalArgumentException 异常。当要输出的偏移量为零时，模式字母 X（大写）将输出 Z，而模式字母 x（消息）将会输出 +00，+0000 或 +00:00。

• 偏移 O

根据模式字母的数量格式化局部偏移。一个字母输出局部偏移的 short 格式，这是局部偏移文本，例如 GMT，有无前导零的小时，2 位可选分秒（如果非零）和冒号，如 GMT+8。4 个模式字母输出 full 格式，这是一个局部偏移文本，例如 GMT，具有 2 位小时和分钟字段、可选秒字段（如果非零）和冒号，例如 GMT+08:00。其他字母数会抛出 IllegalArgumentException 异常。

• 偏移 Z
  根据模式字母的数量格式化偏移量。一个，两个或者三个字母输出小时和分钟，没有冒号，例如，+0130。当偏移量为零时，输出 +0000。四个字母输出 full 格式的局部偏移量，相当于 偏移 O 的四个字母。如果偏移为零，输出相应的局部偏移文本。五个字母输出小时，分钟，可选秒（如果非零），冒号。如果偏移为零，则输出 Z。六位或者更多的字母抛出 IllegalArgumentException 异常。
• 可选部分
  可选部分标记的工作原理与调用 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" }
              ]
          }
      }
   }
}

1. 日期将会被转化为 2016-02-01T00:00:00.000+01:00。

2. now/d 将在 CET 时区四舍五入到一天的开始。

Keyed 响应结果

将 keyed 标志设置为 true 会将唯一的 key 与每个桶关联起来，并且返回每个桶的范围，该范围是哈希格式而不是数组格式。

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

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/elasticsearch73...

译文地址：https://learnku.com/docs/elasticsearch73...