重要: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 当前版本文档。
Elasticsearch 权威指南 [7.7] » 聚合 » 桶(bucket)聚合 » auto_date_histogram 聚合
« adjacency_matrix 聚合 children 聚合 »

自动间隔的日期直方图(auto_date_histogram)聚合

一个类似于日期直方图聚合的多桶聚合，但不是靠给定的 间隔(interval) 来作为每个桶的宽度，而是给定目标桶的数量来指示所需的桶数，并且自动选择桶的间隔以用最好的方式来实现该目标。 返回的桶数将始终小于或等于该目标数。

buckets 字段是可选的，如果未指定，将默认为 10 个桶。

以10个桶为目标进行请求。

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "auto_date_histogram" : {
                "field" : "date",
                "buckets" : 10
            }
        }
    }
}

键(key)

在内部，一个日期被表示为一个64位的数字-一个时间戳，以毫秒为单位。 这些时间戳作为桶的键(key)返回。 key_as_string 是使用 format 参数指定的格式(format)转换为格式化的日期字符串的相同时间戳:

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

POST /sales/_search?size=0
{
    "aggs" : {
        "sales_over_time" : {
            "auto_date_histogram" : {
                "field" : "date",
                "buckets" : 5,
                "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
                }
            ],
            "interval": "1M"
        }
    }
}

间隔(interval)

基于聚合收集的数据选择返回桶的间隔，使得返回的桶的数量小于或等于请求的数量。 返回的间隔可能是：

seconds

以1、5、10和30的倍数

minutes

以1、5、10和30的倍数

hours

以1、3和12的倍数

days

以1和7的倍数

months

以1和3的倍数

years

以1、5、10、20、50和100的倍数

在最坏的情况下，对于请求的桶数，每日桶数太多，返回的桶数将是请求的桶数的1/7。

时区(time zone)

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

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

看下面这个例子：

#添加并索引3个文档
PUT my_index/log/1?refresh
{
  "date": "2015-10-01T00:30:00Z"
}

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

PUT my_index/log/3?refresh
{
  "date": "2015-10-01T02:30:00Z"
}

#搜索
GET my_index/_search?size=0
{
  "aggs": {
    "by_day": {
      "auto_date_histogram": {
        "field":     "date",
        "buckets" : 3
      }
    }
  }
}

如果未指定时区则使用 UTC，从 UTC 时间的 2015年10月1日午夜开始返回3个1小时间隔的桶:

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-10-01T00:00:00.000Z",
          "key": 1443657600000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T01:00:00.000Z",
          "key": 1443661200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T02:00:00.000Z",
          "key": 1443664800000,
          "doc_count": 1
        }
      ],
      "interval": "1h"
    }
  }
}

如果指定了time_zone的值为-01:00，则午夜从 UTC 午夜前一小时开始：

GET my_index/_search?size=0
{
  "aggs": {
    "by_day": {
      "auto_date_histogram": {
        "field":     "date",
        "buckets" : 3,
        "time_zone": "-01:00"
      }
    }
  }
}

现在仍返回3个1小时间隔的桶，但第一个桶开始于2015年9月30日晚上11:00，因为这是该时段在指定时区的当地时间。

{
  ...
  "aggregations": {
    "by_day": {
      "buckets": [
        {
          "key_as_string": "2015-09-30T23:00:00.000-01:00", 
          "key": 1443657600000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T00:00:00.000-01:00",
          "key": 1443661200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2015-10-01T01:00:00.000-01:00",
          "key": 1443664800000,
          "doc_count": 1
        }
      ],
      "interval": "1h"
    }
  }
}

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

当使用跟随 DST(夏令时)变化的时区时，靠近这些变化发生时刻的桶可能与相邻桶的大小略有不同。 例如，在 CET 时区开始夏令时：2016年3月27日凌晨2点，时钟拨快1小时至当地时间凌晨3点。 如果聚合的结果是每日一个桶，则当天的时段将仅保存23小时的数据，而不是其他时段通常的24小时。 对于较短的时间间隔，例如12小时，情况也是如此。 在这里，当夏令时转换发生时，我们在3月27日早上只有一个11小时的桶。

脚本

与普通的 date_histogram（日期直方图） 一样，文档级脚本和值级脚本都受支持。 但是，此聚合不支持min_doc_count、extended_bounds 及 order参数。

参数 minimum_interval

minimum_interval 允许调用者指定应该使用的最小舍入区间。 这可以提高收集过程的效率，因为聚合不会以任何低于 minimum_interval的时间间隔进行舍入。

minimum_interval可以接受的单位有：

  • year
  • month
  • day
  • hour
  • minute
  • second 
POST /sales/_search?size=0
{
    "aggs" : {
        "sale_date" : {
             "auto_date_histogram" : {
                 "field" : "date",
                 "buckets": 10,
                 "minimum_interval": "minute"
             }
         }
    }
}

缺失的值

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

POST /sales/_search?size=0
{
    "aggs" : {
        "sale_date" : {
             "auto_date_histogram" : {
                 "field" : "date",
                 "buckets": 10,
                 "missing": "2000/01/01" 
             }
         }
    }
}

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

« adjacency_matrix 聚合 children 聚合 »