日期字段类型

1.0 版引入

OpenSearch 中的日期可以表示为以下形式之一：

• 一个长整型值，表示自纪元以来的毫秒数。日期在内部以这种形式存储。
• 格式化的字符串。
• 一个整数值，表示自纪元以来的秒数。

为了表示日期范围，存在日期范围字段类型。

示例

创建包含日期字段和两种日期格式的映射

PUT testindex
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date",
        "format" : "strict_date_optional_time||epoch_millis"
      }
    }
  }
}

参数

下表列出了日期字段类型接受的参数。所有参数都是可选的。

格式

OpenSearch 具有内置日期格式，但您也可以创建自己的自定义格式。您可以指定多个日期格式，用 || 分隔。

默认格式

自 OpenSearch 2.12 起，您可以选择使用实验性默认日期格式：strict_date_time_no_millis||strict_date_optional_time||epoch_millis。要使用实验性默认格式，请将 opensearch.experimental.optimization.datetime_formatter_caching.enabled 功能标志设置为 true。有关启用和禁用功能标志的更多信息，请参阅启用实验性功能。

内置格式

大多数日期格式都有对应的 strict_ 版本。当格式以 strict_ 开头时，日期必须具有格式中指定的正确位数。例如，如果格式设置为 strict_year_month_day ("yyyy-MM-dd")，则月份和日期都必须是两位数字。因此，"2020-06-09" 有效，而 "2020-6-9" 无效。

纪元定义为 1970 年 1 月 1 日 00:00:00 UTC。

y: 年
Y: 基于周的年份
M: 月
w: 一年中的序数周，从 01 到 53
d: 日
D: 一年中的序数日，从 001 到 365（闰年为 366）
e: 一周中的序数日，从 1（星期一）到 7（星期日）
H: 小时，从 0 到 23
m: 分钟
s: 秒
S: 秒的小数部分
Z: 时区偏移量（例如，+0400；-0400；-04:00）

数字日期格式

基本日期格式

基本日期格式的组成部分不使用分隔符分隔。例如，“20190323”。

完整日期格式

完整日期格式的组成部分通过 - 分隔日期，通过 : 分隔时间。例如，"2019-03-23T21:34"。

自定义格式

您可以为日期字段创建自定义格式。例如，以下请求指定了一个常见的 "MM/dd/yyyy" 格式的日期

PUT testindex
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date",
        "format" : "MM/dd/yyyy"
      }
    }
  }
}

索引包含日期的文档

PUT testindex/_doc/21 
{
  "release_date" : "03/21/2019"
}

搜索精确日期时，请以相同的格式提供该日期

GET testindex/_search
{
  "query" : {
    "match": {
      "release_date" : {
        "query": "03/21/2019"
      }
    }
  }
}

范围查询默认使用字段的映射格式。您也可以通过提供 format 参数以不同的格式指定日期范围

GET testindex/_search
{
  "query": {
    "range": {
      "release_date": {
        "gte": "2019-01-01",
        "lte": "2019-12-31",
        "format": "yyyy-MM-dd"
      }
    }
  }
}

日期数学

日期字段类型支持使用日期数学在查询中指定持续时间。例如，范围查询中的 gt、gte、lt 和 lte 参数以及 日期范围聚合中的 from 和 to 参数都接受日期数学表达式。

日期数学表达式包含一个固定日期，后面可选地跟着一个或多个数学表达式。固定日期可以是 now（自 epoch 以来的当前日期和时间（以毫秒为单位））或以 || 结尾的字符串，用于指定日期（例如，2022-05-18||）。日期必须采用默认格式（默认情况下为 strict_date_time_no_millis||strict_date_optional_time||epoch_millis）。

如果您在字段映射中指定了多种日期格式，OpenSearch 会使用第一种格式将自 epoch 以来的毫秒值转换为字符串。
如果字段的字段映射不包含任何格式，OpenSearch 会使用 strict_date_optional_time 格式将 epoch 值转换为字符串。

日期数学支持以下数学运算符。

日期数学支持以下时间单位

y: 年
M: 月
w: 周
d: 天
h 或 H: 小时
m: 分钟
s: 秒

表达式示例

以下示例表达式说明了如何使用日期数学

• now+1M: 自 epoch 以来的当前日期和时间（以毫秒为单位），加上 1 个月。
• 2022-05-18||/M: 05/18/2022，四舍五入到月份的开始。解析为 2022-05-01。
• 2022-05-18T15:23||/h: 05/18/2022 的 15:23，四舍五入到小时的开始。解析为 2022-05-18T15。
• 2022-05-18T15:23:17.789||+2M-1d/d: 05/18/2022 的 15:23:17.789，加上 2 个月减去 1 天，四舍五入到天的开始。解析为 2022-07-17。

在范围查询中使用日期数学

以下示例说明了如何在范围查询中使用日期数学。

设置一个索引，其中 release_date 映射为 date

PUT testindex 
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date"
      }
    }
  }
}

将两个文档索引到该索引中

PUT testindex/_doc/1
{
  "release_date": "2022-09-14"
}

PUT testindex/_doc/2
{
  "release_date": "2022-11-15"
}

以下查询搜索 release_date 在 09/14/2022 前后 2 个月零 1 天内的文档。范围的下限四舍五入到 09/14/2022 的当天开始。

GET testindex/_search
{
  "query": {
    "range": {
      "release_date": {
        "gte": "2022-09-14T15:23||/d",
        "lte": "2022-09-14||+2M+1d"
      }
    }
  }
}

响应包含这两个文档

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "testindex",
        "_id" : "2",
        "_score" : 1.0,
        "_source" : {
          "release_date" : "2022-11-14"
        }
      },
      {
        "_index" : "testindex",
        "_id" : "1",
        "_score" : 1.0,
        "_source" : {
          "release_date" : "2022-09-14"
        }
      }
    ]
  }
}