日期直方图聚合 #

date_histogram 聚合使用日期计算来为时间序列数据生成直方图。

相关指南（先读这些） #

例如，您可以找到您的网站每月有多少次访问：

GET sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "logs_per_month": {
      "date_histogram": {
        "field": "@timestamp",
        "interval": "month"
      }
    }
  }
}

返回内容

...
"aggregations" : {
  "logs_per_month" : {
    "buckets" : [
      {
        "key_as_string" : "2020-10-01T00:00:00.000Z",
        "key" : 1601510400000,
        "doc_count" : 1635
      },
      {
        "key_as_string" : "2020-11-01T00:00:00.000Z",
        "key" : 1604188800000,
        "doc_count" : 6844
      },
      {
        "key_as_string" : "2020-12-01T00:00:00.000Z",
        "key" : 1606780800000,
        "doc_count" : 5595
      }
    ]
  }
}

返回内容包含三个月的日志。如果你绘制这些值，你可以看到你的网站每月请求流量的峰值和低谷。

参数说明 #

date_histogram 聚合支持以下参数。

参数	必需/可选	数据类型	描述
`date_histogram`	必填	Object	一个指定日期时间文档字段、间隔、可选格式和时区的对象。
`calendar_interval`	必填	时间间隔	构建每个分组所使用的日期字段。
`format`	可选	String	日期格式字符串。如果省略，日期将输出为 64 位自纪元以来的毫秒整数。
`time_zone`	可选	String	表示 UTC 时间偏移的字符串，可以是 ISO 8601 UTC 偏移（"-07:00"）或 tz 数据库标识符（“America/Los_Angeles”）。

interval 与 calendar_interval / fixed_interval #

interval 参数已被标记为弃用，建议使用以下两个参数之一：

参数	说明
`calendar_interval`	基于日历的间隔，能感知月份天数和闰年。有效值：`minute`、`hour`、`day`、`week`、`month`、`quarter`、`year`
`fixed_interval`	固定长度间隔，不感知日历。有效值如 `30m`、`1h`、`12h`、`1d`

例如，按周统计日志量：

GET sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "logs_per_week": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "week"
      }
    }
  }
}

设置时区 #

日期直方图默认使用 UTC 时区。对于中国地区的数据，通常需要设置时区以获得正确的日期分桶边界：

GET sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "logs_per_day": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "day",
        "time_zone": "+08:00",
        "format": "yyyy-MM-dd"
      }
    }
  }
}

空桶填充 #

默认情况下，没有文档的时间桶不会在结果中出现。设置 min_doc_count 为 0 可以显示空桶，配合 extended_bounds 可以确保结果覆盖指定的完整时间范围：

GET sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "logs_per_day": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "day",
        "min_doc_count": 0,
        "extended_bounds": {
          "min": "2020-10-01",
          "max": "2020-12-31"
        }
      }
    }
  }
}

提示：extended_bounds 不会过滤文档，只是确保在结果中包含该范围内的所有桶，即使桶内没有文档。