Date field type

    • 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.

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

    Parameters

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

    OpenSearch has built-in date formats, but you can also create your own custom formats. The default format is strict_date_optional_time||epoch_millis. You can specify multiple date formats, separated by ||.

    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:
    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)

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

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

    1. PUT testindex
    2. {
    3.   "mappings" : {
    4.     "properties" :  {
    5.       "release_date" : {
    6.         "type" : "date",
    7.         "format" : "MM/dd/yyyy"
    8.       }
    9.     }
    10.   }
    11. }

    Index a document with a date:

    1. PUT testindex/_doc/21 
    2. {
    3.   "release_date" : "03/21/2019"
    4. }

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

    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:

    1. GET testindex/_search
    2. {
    3.   "query": {
    4.     "range": {
    5.         "gte": "2019-01-01",
    6.         "lte": "2019-12-31",
    7.         "format": "yyyy-MM-dd"
    8.       }
    9.     }
    10.   }
    11. }

    Date math

    The date field type supports using date math to specify duration in queries. For example, the , gte, lt, and lte parameters in range queries and the from and to parameters in 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 strict_date_optional_time||epoch_millis format.

    Date math supports the following time units:

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

    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.

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

    Set up an index with release_date mapped as date:

    1. PUT testindex 
    2. {
    3.   "mappings" : {
    4.     "properties" :  {
    5.       "release_date" : {
    6.         "type" : "date"
    7.       }
    8.     }
    9.   }
    10. }

    Index two documents into the index:

    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:

    1. GET testindex/_search
    2. {
    3.   "query": {
    4.     "range": {
    5.       "release_date": {
    6.         "gte": "2022-09-14T15:23||/d",
    7.         "lte": "2022-09-14||+2M+1d"
    8.       }
    9.     }
    10.   }
    11. }
    1. {
    2.   "timed_out" : false,
    3.   "_shards" : {
    4.     "total" : 1,
    5.     "successful" : 1,
    6.     "skipped" : 0,
    7.     "failed" : 0
    8.   },
    9.   "hits" : {
    10.     "total" : {
    11.       "value" : 2,
    12.       "relation" : "eq"
    13.     },
    14.     "max_score" : 1.0,
    15.     "hits" : [
    16.       {
    17.         "_index" : "testindex",
    18.         "_id" : "2",
    19.         "_score" : 1.0,
    20.         "_source" : {
    21.           "release_date" : "2022-11-14"
    22.         }
    23.       },
    24.       {
    25.         "_index" : "testindex",
    26.         "_id" : "1",
    27.         "_score" : 1.0,
    28.         "_source" : {
    29.           "release_date" : "2022-09-14"
    30.         }
    31.       }
    32.     ]
    33.   }