Link Search Menu Expand Document Documentation Menu
文档

自动间隔日期直方图

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

间隔

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

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

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

如果聚合返回过多的桶（例如，每日桶），OpenSearch 将自动减少桶的数量，以确保结果可管理。它不会返回精确数量的请求每日桶，而是将其减少约 1/7。例如，如果您请求 70 个桶，但数据包含过多的每日间隔，OpenSearch 可能只返回 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 OpenSearch",
  "date_posted": "2022-04-17"
}


PUT blogs/_doc/2
{
  "name": "Sparse search in OpenSearch",
  "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 OpenSearch",
  "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 年，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
}

在 OpenSearch 中，日期内部存储为 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 OpenSearch",
  "date_posted": "2022-04-17T01:00:00.000Z"
}


PUT blogs1/_doc/2
{
  "name": "Sparse search in OpenSearch",
  "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"
    }
  }
}

现在，指定 time_zone 为 -02:00

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) 变更的时区时，过渡期附近的桶大小可能与相邻桶的大小略有不同。

剩余 350 字符

有问题？。

想要贡献？或。