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

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

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

» » »

« composite 聚合 date_range 聚合 »

日期直方图(date_histogram)聚合

这种多桶聚合类似于普通的直方图(histogram)聚合，但它只能用于日期或日期范围值。因为 Elasticsearch 中的日期在内部用长整形表示，所以也可以对日期使用普通histogram聚合，但不够精确。这两个API的主要区别在于，日期直方图可以使用日期/时间表达式来指定时间间隔。基于时间的数据需要特殊的支持，因为基于时间的间隔并不总是固定的长度。

日历和固定间隔值

配置日期直方图聚合时，可以通过两种方式指定时间间隔：日历感知(calendar-aware)时间间隔和固定(fixed)时间间隔。

日历感知间隔知道夏令时改变特定日子的长度，月份有不同的天数，闰秒可以附加到特定的年份。

相比之下，固定间隔始终是SI(国际)单位的倍数，并且不会根据日历上下文改变。

组合的`interval`字段已弃用

[7.2] 在7.2版本中废弃。 interval字段已废弃过去，日历和固定时间间隔都是在一个 interval 字段中配置的，这导致了语义混乱。指定 1d 会被认为是一个日历感知时间，而 2d 却被解释为一个固定时间。要获得固定时间类型的“一天”，用户需要指定下一个更小的单位(在本例中是24h)。

这种组合行为对于用户来说通常是未知的，即使知道这种行为，也很难使用且容易混淆。

这种行为已被弃用，取而代之的是两个新的显式字段：calendar_interval 和 fixed_interval。

通过预先在日历和间隔之间进行选择，时间间隔的语义对用户来说是一目了然的，不会有歧义。旧的interval字段会在将来移除。

日历间隔

日历感知间隔是用参数 calendar_interval 配置的。日历间隔只能以单位的“单数”数量指定(1d、1M等)。不支持像 2d这样的倍数，否则会引发异常。

日历间隔可用的单位有：

分钟 (1m): 所有的分钟都从00秒开始。一分钟是指定时区中第一分钟的00秒和下一分钟的00秒之间的时间间隔，用于补偿任何介于其间的闰秒，因此整点后的分钟数和秒数在开始和结束时是相同的。
小时 (1h): 所有的小时都从00分00秒开始。一个小时(1h)是指定时区中第一个小时的00:00分钟和下一个小时的00:00分钟之间的间隔，用于补偿任何介于其间的闰秒，以便在开始和结束时超过该小时的分钟数和秒数是相同的。
天 (1d): 所有的天都在尽可能早的时间开始，通常是00:00:00(午夜)。一天(1d)是指定时区中一天开始和下一天开始之间的时间间隔，用于补偿任何中间的时间变化。
星期 (1w): 一周是指定时区中一周的开始日:小时:分钟:秒(day_of_week:hour:minute:second) 与下一周的同一天和时间之间的间隔。
月 (1M): 一个月是指定时区中一个月的开始日期和时间与下一个月的同一天和时间之间的间隔，因此一个月的开始日期和时间是相同的。
季度 (1q): 一个季度(1q)是一个月的开始日期和一天中的时间与三个月后的同一天和一天中的时间之间的间隔，因此一个月的开始日期和结束日期是相同的。
年 (1y): 一年(1y)是指定时区中一个月的开始日期和时间与下一年的同一天和时间之间的间隔，因此开始和结束时的日期和时间是相同的。

日历间隔的示例

例如，下面是请求以日历时间中的一个月为桶间隔的聚合：

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "calendar_interval" : "month"
            }
        }
    }
}

如果尝试使用日历单位的倍数，聚合就会失败，因为仅支持单个日历单位:

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "calendar_interval" : "2d"
            }
        }
    }
}

{
  "error" : {
    "root_cause" : [...],
    "type" : "x_content_parse_exception",
    "reason" : "[1:82] [date_histogram] failed to parse field [calendar_interval]",
    "caused_by" : {
      "type" : "illegal_argument_exception",
      "reason" : "The supplied interval [2d] could not be parsed as a calendar interval.",
      "stack_trace" : "java.lang.IllegalArgumentException: The supplied interval [2d] could not be parsed as a calendar interval."
    }
  }
}

固定间隔

固定间隔是用参数 fixed_interval 配置的。

与日历感知间隔不同，固定间隔是固定数量的国际单位制(SI)单位，无论它们在日历上的位置如何，都不会偏离。一秒钟总是由1000毫秒组成。这允许以支持单位的任何倍数值指定固定间隔。

然而，这意味着固定的间隔不能表达其他单位，如“月(month)”，因为一个月的持续时间不是一个固定的量。试图指定月或季度(quarter)等日历间隔将引发异常。

固定间隔支持的单位有：

毫秒 (ms)
秒 (s): 定义为每个1000毫秒
分钟 (m): 所有分钟都从00秒开始。定义为每个60秒(60,000毫秒)
小时 (h): 所有小时都从00分00秒开始。定义为每60分钟(3,600,000毫秒)
天 (d): 所有天都在尽可能早的时间开始，通常是00:00:00(午夜)。定义为24小时(86,400,000毫秒)

固定价格的示例

如果我们尝试重新创建之前的calendar_interval的“月”，我们可以用30天的固定天数来近似：

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "fixed_interval" : "30d"
            }
        }
    }
}

但是，如果我们尝试使用不支持的日历单位，如“周(w)”，就会得到一个异常：

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "fixed_interval" : "2w"
            }
        }
    }
}

{
  "error" : {
    "root_cause" : [...],
    "type" : "x_content_parse_exception",
    "reason" : "[1:82] [date_histogram] failed to parse field [fixed_interval]",
    "caused_by" : {
      "type" : "illegal_argument_exception",
      "reason" : "failed to parse setting [date_histogram.fixedInterval] with value [2w] as a time value: unit is missing or unrecognized",
      "stack_trace" : "java.lang.IllegalArgumentException: failed to parse setting [date_histogram.fixedInterval] with value [2w] as a time value: unit is missing or unrecognized"
    }
  }
}

注意

在任何情况下，当指定的结束时间不存在时，实际结束时间是指定结束时间后最近的可用时间。

广泛发布的应用程序还必须考虑一些不确定因素，比如一些国家在12点01分开始和停止夏令时，因此每年都会有一分钟是周日，然后接下来的59分钟又回到了周六，以及一些国家决定跨越国际日期变更线。这种情况使得不规则时区偏移看起来很容易。

与往常一样，严格的测试，尤其是围绕时间变化事件，将确保你的时间间隔规格是你想要的。

警告：为避免意外结果，所有连接的服务器和客户端都必须同步到可靠的网络时间服务。

不支持带小数点的时间值，但是可以通过转换到另一个时间单位来解决这个问题(例如，可以将1.5h指定为90m)。

还可以使用时间单位解析支持的缩写来指定时间值。

key

在内部，日期被表示为一个64位的数字，该数字表示一个以毫秒为单位的时间戳，该时间戳自UTC时间1970/1/1午夜开始。这些时间戳作为桶的 key 返回。 key_as_string 是一个使用参数format规范转换为格式化的日期字符串的相同的时间戳：

如果未指定 format，将使用字段映射中指定的第一个日期格式。

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "calendar_interval" : "1M",
                "format" : "yyyy-MM-dd" 
            }
        }
    }
}

支持日期格式模式表达式

响应：

{
    ...
    "aggregations": {
        "sales_over_time": {
            "buckets": [
                {
                    "key_as_string": "2015-01-01",
                    "key": 1420070400000,
                    "doc_count": 3
                },
                {
                    "key_as_string": "2015-02-01",
                    "key": 1422748800000,
                    "doc_count": 2
                },
                {
                    "key_as_string": "2015-03-01",
                    "key": 1425168000000,
                    "doc_count": 2
                }
            ]
        }
    }
}

时区

日期时间以 UTC 存储在 Elasticsearch 中。默认情况下，所有的分桶和舍入也在 UTC 中完成。 time_zone 参数可用于指示分桶时应该使用不同的时区。

时区可以指定为 ISO 8601 UTC 时差(例如+01:00 或 -08:00)，也可以指定为时区id(在TZ数据库中使用的标识符)，比如America/Los_Angeles。

看下面的例子：

PUT my_index/_doc/1?refresh
{
  "date": "2015-10-01T00:30:00Z"
}

PUT my_index/_doc/2?refresh
{
  "date": "2015-10-01T01:30:00Z"
}

GET my_index/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day"
      }
    }
  }
}

如果不指定时区，则使用UTC。这将导致这两个文档被放入同一天的桶中，该桶从UTC时间2015年10月1日午夜开始：

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-10-01T00:00:00.000Z",
          "key":           1443657600000,
          "doc_count":     2
        }
      ]
    }
  }
}

如果指定了 time_zone 为 -01:00，则该时区中的午夜比UTC的午夜早一个小时：

GET my_index/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day",
        "time_zone": "-01:00"
      }
    }
  }
}

现在，第一份文件落入2015年9月30日的桶中，而第二份文件落入2015年10月1日的桶中：

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T00:00:00.000-01:00", 
          "key": 1443574800000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T00:00:00.000-01:00", 
          "key": 1443661200000,
          "doc_count": 1
        }
      ]
    }
  }
}

key_as_string的值表示指定时区中每天的午夜。

当使用随DST(夏令时)变化的时区时，接近这些变化发生时刻的桶的大小可能会与你预期要用的interval略有不同。例如，考虑在CET时区开始夏令时：2016年3月27日凌晨2点，时钟拨快1小时至当地时间凌晨3点。如果使用 day 作为 interval，则覆盖该天的桶将只保存23小时的数据，而不是其他桶通常的24小时。对于较短的时间间隔也是如此，比如12小时，在3月27日早上DST转换发生时，桶里只有11个小时。

时差(offset)

使用 offset 参数按指定的正(+)或负(-)偏移量持续时间来更改每个桶的起始值，例如1h表示一个小时，1d表示一天。有关更多可能的持续时间选项，请参见时间单位(time units)。

例如，当使用day作为时间间隔时，每个桶的时间区间从午夜到午夜。将参数 offset 设置为 +6h 会将每个桶的时间区间更改为从早上6点到早上6点：

PUT my_index/_doc/1?refresh
{
  "date": "2015-10-01T05:30:00Z"
}

PUT my_index/_doc/2?refresh
{
  "date": "2015-10-01T06:30:00Z"
}

GET my_index/_search?size=0
{
  "aggs": {
    "by_day": {
      "date_histogram": {
        "field":     "date",
        "calendar_interval":  "day",
        "offset":    "+6h"
      }
    }
  }
}

上面的请求的每个桶不是从午夜开始，而是从早上6点开始：

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T06:00:00.000Z",
          "key": 1443592800000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T06:00:00.000Z",
          "key": 1443679200000,
          "doc_count": 1
        }
      ]
    }
  }
}

在进行 time_zone 调整后，计算每个桶的起始 offset。

keyed 响应

将 keyed 标志设置为 true，会将唯一的字符串键与每个桶相关联，并将范围作为哈希而不是数组返回：

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "date_histogram" : {
                "field" : "date",
                "calendar_interval" : "1M",
                "format" : "yyyy-MM-dd",
                "keyed": true
            }
        }
    }
}

响应：

{
    ...
    "aggregations": {
        "sales_over_time": {
            "buckets": {
                "2015-01-01": {
                    "key_as_string": "2015-01-01",
                    "key": 1420070400000,
                    "doc_count": 3
                },
                "2015-02-01": {
                    "key_as_string": "2015-02-01",
                    "key": 1422748800000,
                    "doc_count": 2
                },
                "2015-03-01": {
                    "key_as_string": "2015-03-01",
                    "key": 1425168000000,
                    "doc_count": 2
                }
            }
        }
    }
}

脚本

与普通 histogram 聚合一样，文档级脚本和值级脚本都是支持的。你可以使用 order 设置控制返回的桶的顺序，并根据 min_doc_count 设置过滤返回的桶(默认情况下，将返回第一个与文档匹配的桶和最后一个桶之间的所有桶)。该直方图还支持 extended_bounds 设置，该设置允许将直方图的边界扩展到数据本身之外。更多信息请参考扩展的边界。

缺失的值

参数 missing 定义了如何处理缺少值的文档。默认情况下，它们被忽略，但是也可以将它们视为有一个值。

POST /sales/_search?size=0
{
    "aggs" : {
        "sale_date" : {
             "date_histogram" : {
                 "field" : "date",
                 "calendar_interval": "year",
                 "missing": "2000/01/01" 
             }
         }
    }
}

publish_date 字段没有值的文档将与 2000-01-01落入同一个桶。

排序(order)

默认情况下，返回的桶按照他们的 key 升序排列，但是你可以使用 order 设置来控制排序。此设置支持与terms 聚合相同的 order 功能。

使用脚本按某一天是一周中的第几天进行聚合

当你需要按某一天是一周中的第几天汇总结果时，请使用返回某一天是一周中的第几天的脚本：

POST /sales/_search?size=0
{
    "aggs": {
        "dayOfWeek": {
            "terms": {
                "script": {
                    "lang": "painless",
                    "source": "doc['date'].value.dayOfWeekEnum.value"
                }
            }
        }
    }
}

响应：

{
  ...
  "aggregations": {
    "dayOfWeek": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "7",
          "doc_count": 4
        },
        {
          "key": "4",
          "doc_count": 3
        }
      ]
    }
  }
}

响应将包含以某一天是一周中的第几天为key的所有桶：1表示星期一，2表示星期二，...7表示星期天。

« composite 聚合 date_range 聚合 »

日期直方图(date_histogram)聚合

日历和固定间隔值

组合的interval字段已弃用

日历间隔

日历间隔的示例

固定间隔

固定价格的示例

注意

key

时区

时差(offset)

keyed 响应

脚本

缺失的值

排序(order)

使用脚本按某一天是一周中的第几天进行聚合

组合的`interval`字段已弃用