自动间隔日期直方图

与必须指定间隔的日期直方图聚合类似，auto_date_histogram 是一种多桶聚合，它会根据您提供的桶数量和数据的时范围自动创建日期直方图桶。返回的实际桶数量始终小于或等于您指定的桶数量。当您处理时间序列数据，并希望在不同时间间隔内可视化或分析数据，而无需手动指定间隔大小时，此聚合特别有用。

间隔

桶间隔是根据收集的数据选择的，以确保返回的桶数量小于或等于请求的数量。

下表列出了每个时间单位可能返回的间隔。

单位	间隔
秒	1、5、10 和 30 的倍数
分钟	1、5、10 和 30 的倍数
小时	1、3 和 12 的倍数
天	1 和 7 的倍数
月	1 和 3 的倍数
年	1、5、10、20、50 和 100 的倍数

如果聚合返回的桶太多（例如，按天分桶），UDB-SX 将自动减少桶数量以确保结果易于管理。它不会返回所请求的确切数量的天级桶，而是会按大约 1/7 的系数减少。例如，如果您请求 70 个桶但数据包含太多天级间隔，UDB-SX 可能只返回 10 个桶，将数据分组到更大的间隔（例如按周），以避免返回过多结果。这有助于优化聚合，并在数据量过大时防止产生过多的细节。

示例

在以下示例中，您将搜索一个包含博客文章的索引。

首先，为此索引创建映射，并将 date_posted 字段指定为 date 类型：

PUT blogs
{
  "mappings" : {
    "properties" :  {
      "date_posted" : {
        "type" : "date",
        "format" : "yyyy-MM-dd"
      }
    }
  }
}

接下来，将以下文档索引到 blogs 索引中：

PUT blogs/_doc/1
{
  "name": "Semantic search in UDB-SX",
  "date_posted": "2022-04-17"
}

PUT blogs/_doc/2
{
  "name": "Sparse search in UDB-SX",
  "date_posted": "2022-05-02"
}

PUT blogs/_doc/3
{
  "name": "Distributed tracing with Data Prepper",
  "date_posted": "2022-04-25"
}

PUT blogs/_doc/4
{
  "name": "Observability in UDB-SX",
  "date_posted": "2023-03-23"
}

要使用 auto_date_histogram 聚合，请指定包含日期或时间戳值的字段。例如，要按 date_posted 将博客文章聚合到两个桶中，请发送以下请求：

GET /blogs/_search
{
  "size": 0,
  "aggs": {
    "histogram": {
      "auto_date_histogram": {
        "field": "date_posted",
        "buckets": 2
      }
    }
  }
}

响应显示博客文章被聚合到两个桶中。间隔自动设置为 1 年，所有 3 篇 2022 年的博客文章收集在一个桶中，2023 年的博客文章在另一个桶中：

{
  "took": 20,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "histogram": {
      "buckets": [
        {
          "key_as_string": "2022-01-01",
          "key": 1640995200000,
          "doc_count": 3
        },
        {
          "key_as_string": "2023-01-01",
          "key": 1672531200000,
          "doc_count": 1
        }
      ],
      "interval": "1y"
    }
  }
}

返回的桶

每个桶包含以下信息：

{
  "key_as_string": "2023-01-01",
  "key": 1672531200000,
  "doc_count": 1
}

在 UDB-SX 中，日期在内部存储为 64 位整数，表示自纪元以来的毫秒时间戳。在聚合响应中，每个桶的 key 以此类时间戳形式返回。key_as_string 值显示相同的时间戳，但根据 format 参数格式化为日期字符串。doc_count 字段包含桶中的文档数量。

参数

自动间隔日期直方图聚合接受以下参数。

参数	数据类型	描述
`field`	字符串	要进行聚合的字段。该字段必须包含日期或时间戳值。`field` 或 `script` 必须指定一个。
`buckets`	整数	期望的桶数量。返回的桶数量小于或等于期望的数量。可选。默认值为 `10`。
`minimum_interval`	字符串	要使用的最小间隔。指定最小间隔可以使聚合过程更高效。有效值为 `year`、`month`、`day`、`hour`、`minute` 和 `second`。可选。
`time_zone`	字符串	指定用于分桶和舍入的时区，而不是默认时区（UTC）。您可以将 `time_zone` 参数指定为 UTC 偏移量，例如 `-04:00`，或 IANA 时区 ID，例如 `America/New_York`。可选。默认值为 `UTC`。更多信息，请参阅时区。
`format`	字符串	返回表示桶键的日期的格式。可选。默认值为字段映射中指定的格式。更多信息，请参阅日期格式。
`script`	字符串	用于将值聚合到桶中的文档级或值级脚本。`field` 或 `script` 必须指定一个。
`missing`	字符串	指定如何处理字段值缺失的文档。默认情况下，此类文档被忽略。如果您在 `missing` 参数中指定一个日期值，则字段值缺失的所有文档都将被收集到具有该指定日期的桶中。

日期格式

如果您不指定 format 参数，则将使用字段映射中定义的格式（如前面的响应所示）。要修改格式，请指定 format 参数：

GET /blogs/_search
{
  "size": 0,
  "aggs": {
    "histogram": {
      "auto_date_histogram": {
        "field": "date_posted",
        "format": "yyyy-MM-dd HH:mm:ss"
      }
    }
  }
}

key_as_string 字段现在以指定的格式返回：

{
  "key_as_string": "2023-01-01 00:00:00",
  "key": 1672531200000,
  "doc_count": 1
}

或者，您可以指定内置的日期格式之一：

GET /blogs/_search
{
  "size": 0,
  "aggs": {
    "histogram": {
      "auto_date_histogram": {
        "field": "date_posted",
        "format": "basic_date_time_no_millis"
      }
    }
  }
}

key_as_string 字段现在以指定的格式返回：

{
  "key_as_string": "20230101T000000Z",
  "key": 1672531200000,
  "doc_count": 1
}

时区

默认情况下，日期以 UTC 格式存储和处理。time_zone 参数允许您为分桶指定不同的时区。您可以将 time_zone 参数指定为 UTC 偏移量，例如 -04:00，或 IANA 时区 ID，例如 America/New_York。

例如，将以下文档索引到一个索引中：

PUT blogs1/_doc/1
{
  "name": "Semantic search in UDB-SX",
  "date_posted": "2022-04-17T01:00:00.000Z"
}

PUT blogs1/_doc/2
{
  "name": "Sparse search in UDB-SX",
  "date_posted": "2022-04-17T04:00:00.000Z"
}

首先，在不指定时区的情况下运行聚合：

GET /blogs1/_search
{
  "size": 0,
  "aggs": {
    "histogram": {
      "auto_date_histogram": {
        "field": "date_posted",
        "buckets": 2,
        "format": "yyyy-MM-dd HH:mm:ss"
      }
    }
  }
}

响应包含两个 3 小时桶，从 2022 年 4 月 17 日 UTC 午夜开始：

{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "histogram": {
      "buckets": [
        {
          "key_as_string": "2022-04-17 01:00:00",
          "key": 1650157200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2022-04-17 04:00:00",
          "key": 1650168000000,
          "doc_count": 1
        }
      ],
      "interval": "3h"
    }
  }
}

现在，指定一个 -02:00 的 time_zone：

GET /blogs1/_search
{
  "size": 0,
  "aggs": {
    "histogram": {
      "auto_date_histogram": {
        "field": "date_posted",
        "buckets": 2,
        "format": "yyyy-MM-dd HH:mm:ss",
        "time_zone": "-02:00"
      }
    }
  }
}

响应包含两个桶，其开始时间偏移了 2 小时，从 2022 年 4 月 16 日 23:00 开始：

{
  "took": 17,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "histogram": {
      "buckets": [
        {
          "key_as_string": "2022-04-16 23:00:00",
          "key": 1650157200000,
          "doc_count": 1
        },
        {
          "key_as_string": "2022-04-17 02:00:00",
          "key": 1650168000000,
          "doc_count": 1
        }
      ],
      "interval": "3h"
    }
  }
}

当使用具有夏令时 (DST) 变化的时区时，过渡时间附近的桶的大小可能与相邻桶的大小略有不同。