Link Search Menu Expand Document Documentation Menu

Date field type

A date in OpenSearch can be represented as one of the following:

  • A long value that corresponds to milliseconds since the epoch (the value must be non-negative). Dates are stored in this form internally.
  • A formatted string.
  • An integer value that corresponds to seconds since the epoch (the value must be non-negative).

To represent date ranges, there is a date range field type.

Example

Create a mapping with a date field and two date formats:

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

Parameters

The following table lists the parameters accepted by date field types. All parameters are optional.

Parameter Description
boost A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field’s relevance. Values between 0.0 and 1.0 decrease the field’s relevance. Default is 1.0.
doc_values A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is false.
format The format for parsing dates. Default is strict_date_time_no_millis||strict_date_optional_time||epoch_millis.
ignore_malformed A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is false.
index A Boolean value that specifies whether the field should be searchable. Default is true.
locale A region- and language-specific way of representing the date. Default is ROOT (a region- and language-neutral locale).
meta Accepts metadata for this field.
null_value A value to be used in place of null. Must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is null. Default is null.
store A Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is false.

Formats

OpenSearch has built-in date formats, but you can also create your own custom formats. You can specify multiple date formats, separated by ||.

Default format

As of OpenSearch 2.12, the default date format is strict_date_time_no_millis||strict_date_optional_time||epoch_millis. To revert the default format back to strict_date_optional_time||epoch_millis (the default format for OpenSearch 2.11 and earlier), set the opensearch.experimental.optimization.datetime_formatter_caching.enabled feature flag to false. For more information about enabling and disabling feature flags, see Enabling experimental features.

Built-in formats

Most of the date formats have a strict_ counterpart. When the format starts with strict_, the date must have the correct number of digits specified in the format. For example, if the format is set to strict_year_month_day ("yyyy-MM-dd"), both month and day have to be two-digit numbers. So, "2020-06-09" is valid, while "2020-6-9" is invalid.

Epoch is defined as 00:00:00 UTC on January 1, 1970.

y: year
Y: week-based year
M: month
w: ordinal week of the year from 01 to 53
d: day
D: ordinal day of the year from 001 to 365 (366 for leap years)
e: ordinal day of the week from 1 (Monday) to 7 (Sunday)
H: hour from 0 to 23
m: minute
s: second
S: fraction of a second
Z: time zone offset (for example, +0400; -0400; -04:00)

Numeric date formats

Format name and description Examples
epoch_millis
The number of milliseconds since the epoch. Minimum is -263. Maximum is 263 − 1.
1553391286000
epoch_second
The number of seconds since the epoch. Minimum is -263 ÷ 1000. Maximum is (263 − 1) ÷ 1000.
1553391286

Basic date formats

Components of basic date formats are not separated by a delimiter. For example, “20190323”.

Format name and description Pattern and examples
Dates  
basic_date_time
A basic date and time separated by T.
"yyyyMMddTHHmmss.SSSZ"
"20190323T213446.123-04:00"
basic_date_time_no_millis
A basic date and time without milliseconds, separated by T.
"yyyyMMddTHHmmssZ"
"20190323T213446-04:00"
basic_date
A date with a four-digit year, two-digit month, and two-digit day.
"yyyyMMdd"<br>"20190323"
Times  
basic_time
A time with a two-digit hour, two-digit minute, two-digit second, three-digit millisecond, and time zone offset.
"HHmmss.SSSZ"
"213446.123-04:00"
basic_time_no_millis
A basic time without milliseconds.
"HHmmssZ"
"213446-04:00"
T times  
basic_t_time
A basic time preceded by T.
"THHmmss.SSSZ"
"T213446.123-04:00"
basic_t_time_no_millis
A basic time without milliseconds, preceded by T.
"THHmmssZ"
"T213446-04:00"
Ordinal dates  
basic_ordinal_date_time
A full ordinal date and time.
"yyyyDDDTHHmmss.SSSZ"
"2019082T213446.123-04:00"
basic_ordinal_date_time_no_millis
A full ordinal date and time without milliseconds.
"yyyyDDDTHHmmssZ"
"2019082T213446-04:00"
basic_ordinal_date
A date with a four-digit year and three-digit ordinal day of the year.
"yyyyDDD"
"2019082"
Week-based dates  
basic_week_date_time
strict_basic_week_date_time
A full week-based date and time separated by T.
"YYYYWwweTHHmmss.SSSZ"
"2019W126213446.123-04:00"
basic_week_date_time_no_millis
strict_basic_week_date_time_no_millis
A basic week-based year date and time without milliseconds, separated by T.
"YYYYWwweTHHmmssZ"
“2019W126213446-04:00”
basic_week_date
strict_basic_week_date
A full week-based date with a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week separated by W.
"YYYYWwwe"
"2019W126"

Full date formats

Components of full date formats are separated by a - delimiter for date and : delimiter for time. For example, "2019-03-23T21:34".

Format name and description Pattern and examples
Dates  
date_optional_time
strict_date_optional_time
A generic full date and time. Year is required. Month, day, and time are optional. Time is separated from date by T.
Multiple patterns.
"2019--03--23T21:34:46.123456789--04:00"
"2019-03-23T21:34:46"
"2019-03-23T21:34"
"2019"
strict_date_optional_time_nanos
A generic full date and time. Year is required. Month, day, and time are optional. If time is specified, it must contain hours, minutes, and seconds, but fraction of a second is optional. Fraction of a second is one to nine digits long and has nanosecond resolution. Time is separated from date by T.
Multiple patterns.
"2019-03-23T21:34:46.123456789-04:00"
"2019-03-23T21:34:46"
"2019"
date_time
strict_date_time
A full date and time separated by T.
"yyyy-MM-ddTHH:mm:ss.SSSZ"
"2019-03-23T21:34:46.123-04:00"
date_time_no_millis
strict_date_time_no_millis
A full date and time without milliseconds, separated by T.
"yyyy-MM-dd'T'HH:mm:ssZ"
"2019-03-23T21:34:46-04:00"
date_hour_minute_second_fraction
strict_date_hour_minute_second_fraction
A full date, two-digit hour, two-digit minute, two-digit second, and one- to nine-digit fraction of a second separated by T.
"yyyy-MM-ddTHH:mm:ss.SSSSSSSSS"
"2019-03-23T21:34:46.123456789"
"2019-03-23T21:34:46.1"
date_hour_minute_second_millis
strict_date_hour_minute_second_millis
A full date, two-digit hour, two-digit minute, two-digit second, and three-digit millisecond separated by T.
"yyyy-MM-ddTHH:mm:ss.SSS"
"2019-03-23T21:34:46.123"
date_hour_minute_second
strict_date_hour_minute_second
A full date, two-digit hour, two-digit minute, and two-digit second separated by T.
"yyyy-MM-ddTHH:mm:ss"
"2019-03-23T21:34:46"
date_hour_minute
strict_date_hour_minute
A full date, two-digit hour, and two-digit minute.
"yyyy-MM-ddTHH:mm"
"2019-03-23T21:34"
date_hour
strict_date_hour
A full date and two-digit hour, separated by T.
"yyyy-MM-ddTHH"
"2019-03-23T21"
date
strict_date
A four-digit year, two-digit month, and two-digit day.
"yyyy-MM-dd"
"2019-03-23"
year_month_day
strict_year_month_day
A four-digit year, two-digit month, and two-digit day.
"yyyy-MM-dd"
"2019-03-23"
year_month
strict_year_month
A four-digit year and two-digit month.
"yyyy-MM"
"2019-03"
year
strict_year
A four-digit year.
"yyyy"
"2019"
rfc3339_lenient
An RFC3339 compatible DateTimeFormatter which is much faster than other full date-lenient formats like strict_date_optional_time
"YYYY"
"2019"
"YYYY-MM"
"2019-03"
"YYYY-MM-DD"
"2019-03-23"
"YYYY-MM-DDThh:mmTZD"
"2019-03-23T21:34Z"
"YYYY-MM-DDThh:mm:ssTZD"
"2019-03-23T21:34:46Z"
"YYYY-MM-DDThh:mm:ss.sTZD"
"2019-03-23T21:34:46.123456789-04:00"
"YYYY-MM-DDThh:mm:ss,sTZD"
"2019-03-23T21:34:46,123456789-04:00"
Times  
time
strict_time
A two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and time zone offset.
"HH:mm:ss.SSSSSSSSSZ"
"21:34:46.123456789-04:00"
"21:34:46.1-04:00"
time_no_millis
strict_time_no_millis
A two-digit hour, two-digit minute, two-digit second, and time zone offset.
"HH:mm:ssZ"
"21:34:46-04:00"
hour_minute_second_fraction
strict_hour_minute_second_fraction
A two-digit hour, two-digit minute, two-digit second, and one- to nine-digit fraction of a second.
"HH:mm:ss.SSSSSSSSS"
"21:34:46.1"
"21:34:46.123456789"
hour_minute_second_millis
strict_hour_minute_second_millis
A two-digit hour, two-digit minute, two-digit second, and three-digit millisecond.
"HH:mm:ss.SSS"
"21:34:46.123"
hour_minute_second
strict_hour_minute_second
A two-digit hour, two-digit minute, and two-digit second.
"HH:mm:ss"
"21:34:46"
hour_minute
strict_hour_minute
A two-digit hour and two-digit minute.
"HH:mm"
"21:34"
hour
strict_hour
A two-digit hour.
"HH"
"21"
T times  
t_time
strict_t_time
A two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and time zone offset, preceded by T.
"THH:mm:ss.SSSSSSSSSZ"<br>"T21:34:46.123456789-04:00"
"T21:34:46.1-04:00"
t_time_no_millis
strict_t_time_no_millis
A two-digit hour, two-digit minute, two-digit second, and time zone offset, preceded by T.
"THH:mm:ssZ"
"T21:34:46-04:00"
Ordinal dates  
ordinal_date_time
strict_ordinal_date_time
A full ordinal date and time separated by T.
"yyyy-DDDTHH:mm:ss.SSSZ"
"2019-082T21:34:46.123-04:00"
ordinal_date_time_no_millis
strict_ordinal_date_time_no_millis
A full ordinal date and time without milliseconds, separated by T.
"yyyy-DDDTHH:mm:ssZ"
"2019-082T21:34:46-04:00"
ordinal_date
strict_ordinal_date
A full ordinal date with a four-digit year and three-digit ordinal day of the year.
"yyyy-DDD"
"2019-082"
Week-based dates  
week_date_time
strict_week_date_time
A full week-based date and time separated by T. Week date is a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week. Time is a two-digit hour, two-digit minute, two-digit second, one- to nine-digit fraction of a second, and a time zone offset.
"YYYY-Www-eTHH:mm:ss.SSSSSSSSSZ"
"2019-W12-6T21:34:46.1-04:00"
"2019-W12-6T21:34:46.123456789-04:00"
week_date_time_no_millis
strict_week_date_time_no_millis
A full week-based date and time without milliseconds, separated by T. Week date is a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week. Time is a two-digit hour, two-digit minute, two-digit second, and time zone offset.
"YYYY-Www-eTHH:mm:ssZ"
"2019-W12-6T21:34:46-04:00"
week_date
strict_week_date
A full week-based date with a four-digit week-based year, two-digit ordinal week of the year, and one-digit ordinal day of the week.
"YYYY-Www-e"
"2019-W12-6"
weekyear_week_day
strict_weekyear_week_day
A four-digit week-based year, two-digit ordinal week of the year, and one digit day of the week.
"YYYY-'W'ww-e"
"2019-W12-6"
weekyear_week
strict_weekyear_week
A four-digit week-based year and two-digit ordinal week of the year.
"YYYY-Www"
"2019-W12"
weekyear
strict_weekyear
A four-digit week-based year.
"YYYY"
"2019"

Custom formats

You can create custom formats for date fields. For example, the following request specifies a date in the common "MM/dd/yyyy" format:

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

Index a document with a date:

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

When searching for an exact date, provide that date in the same format:

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

Range queries by default use the field’s mapped format. You can also specify the range of dates in a different format by providing the format parameter:

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

Date math

The date field type supports using date math to specify durations in queries. For example, the gt, gte, lt, and lte parameters in range queries and the from and to parameters in date range aggregations accept date math expressions.

A date math expression contains a fixed date, optionally followed by one or more mathematical expressions. The fixed date may be either now (current date and time in milliseconds since the epoch) or a string ending with || that specifies a date (for example, 2022-05-18||). The date must be in the default format (which is strict_date_time_no_millis||strict_date_optional_time||epoch_millis by default).

If you specify multiple date formats in the field mapping, OpenSearch uses the first format to convert the milliseconds since the epoch value to a string.
If a field mapping for a field contains no format, OpenSearch uses the strict_date_optional_time format to convert the epoch value to a string.

Date math supports the following mathematical operators.

Operator Description Example
+ Addition +1M: Add 1 month.
- Subtraction -1y: Subtract 1 year.
/ Rounding down /h: Round to the beginning of the hour.

Date math supports the following time units:

y: Years
M: Months
w: Weeks
d: Days
h or H: Hours
m: Minutes
s: Seconds

Example expressions

The following example expressions illustrate using date math:

  • now+1M: The current date and time in milliseconds since the epoch, plus 1 month.
  • 2022-05-18||/M: 05/18/2022, rounded to the beginning of the month. Resolves to 2022-05-01.
  • 2022-05-18T15:23||/h: 15:23 on 05/18/2022, rounded to the beginning of the hour. Resolves to 2022-05-18T15.
  • 2022-05-18T15:23:17.789||+2M-1d/d: 15:23:17.789 on 05/18/2022 plus 2 months minus 1 day, rounded to the beginning of the day. Resolves to 2022-07-17.

Using date math in a range query

The following example illustrates using date math in a range query.

Set up an index with release_date mapped as date:

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

Index two documents into the index:

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

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

The following query searches for documents with release_date within 2 months and 1 day of 09/14/2022. The lower boundary of the range is rounded to the beginning of the day on 09/14/2022:

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

The response contains both documents:

{
  "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"
        }
      }
    ]
  }
}