IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Boolean field type Date nanoseconds field type »
Elastic Docs ›Elasticsearch Guide [7.12] ›Mapping ›Field data types

Date field type

edit

Date field type

edit

JSON doesn’t have a date data type, so dates in Elasticsearch can either be:

  • strings containing formatted dates, e.g. "2015-01-01" or "2015/01/01 12:10:30".
  • a number representing milliseconds-since-the-epoch.
  • a number representing seconds-since-the-epoch (configuration).

Values for milliseconds-since-the-epoch must be non-negative. Use a formatted date to represent dates before 1970.

Internally, dates are converted to UTC (if the time-zone is specified) and stored as a long number representing milliseconds-since-the-epoch.

Queries on dates are internally converted to range queries on this long representation, and the result of aggregations and stored fields is converted back to a string depending on the date format that is associated with the field.

Dates will always be rendered as strings, even if they were initially supplied as a long in the JSON document.

Date formats can be customised, but if no format is specified then it uses the default:

    "strict_date_optional_time||epoch_millis"

This means that it will accept dates with optional timestamps, which conform to the formats supported by strict_date_optional_time or milliseconds-since-the-epoch.

For instance:

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "date": {
        "type": "date" 
      }
    }
  }
}

PUT my-index-000001/_doc/1
{ "date": "2015-01-01" } 

PUT my-index-000001/_doc/2
{ "date": "2015-01-01T12:10:30Z" } 

PUT my-index-000001/_doc/3
{ "date": 1420070400001 } 

GET my-index-000001/_search
{
  "sort": { "date": "asc"} 
}

The date field uses the default format.

This document uses a plain date.

This document includes a time.

This document uses milliseconds-since-the-epoch.

Note that the sort values that are returned are all in milliseconds-since-the-epoch.

Dates will accept numbers with a decimal point like {"date": 1618249875.123456} but there are some cases (#70085) where we’ll lose precision on those dates so should avoid them.

Multiple date formats

edit

Multiple formats can be specified by separating them with || as a separator. Each format will be tried in turn until a matching format is found. The first format will be used to convert the milliseconds-since-the-epoch value back into a string.

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "date": {
        "type":   "date",
        "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
      }
    }
  }
}

Parameters for date fields

edit

The following parameters are accepted by date fields:

boost

Mapping field-level query time boosting. Accepts a floating point number, defaults to 1.0.

doc_values

Should the field be stored on disk in a column-stride fashion, so that it can later be used for sorting, aggregations, or scripting? Accepts true (default) or false.

format

The date format(s) that can be parsed. Defaults to strict_date_optional_time||epoch_millis.

locale

The locale to use when parsing dates since months do not have the same names and/or abbreviations in all languages. The default is the ROOT locale,

ignore_malformed

If true, malformed numbers are ignored. If false (default), malformed numbers throw an exception and reject the whole document.

index

Should the field be searchable? Accepts true (default) and false.

null_value

Accepts a date value in one of the configured format's as the field which is substituted for any explicit null values. Defaults to null, which means the field is treated as missing.

store

Whether the field value should be stored and retrievable separately from the _source field. Accepts true or false (default).

meta

Metadata about the field.

Epoch seconds

edit

If you need to send dates as seconds-since-the-epoch then make sure the format lists epoch_second:

PUT my-index-000001
{
  "mappings": {
    "properties": {
      "date": {
        "type":   "date",
        "format": "strict_date_optional_time||epoch_second"
      }
    }
  }
}

PUT my-index-000001/_doc/example?refresh
{ "date": 1618321898 }

POST my-index-000001/_search
{
  "fields": [ {"field": "date"}],
  "_source": false
}

Which will reply with a date like:

{
  "hits": {
    "hits": [
      {
        "_id": "example",
        "_index": "my-index-000001",
        "_type": "_doc",
        "_score": 1.0,
        "fields": {
          "date": ["2021-04-13T13:51:38.000Z"]
        }
      }
    ]
  }
}
« Boolean field type Date nanoseconds field type »