IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Date datatype

edit

Date datatype

edit

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

strings containing formatted dates, e.g. "2015-01-01" or "2015/01/01 12:10:30".
a long number representing milliseconds-since-the-epoch.
an integer representing seconds-since-the-epoch.

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
{
  "mappings": {
    "_doc": {
      "properties": {
        "date": {
          "type": "date" 
        }
      }
    }
  }
}

PUT my_index/_doc/1
{ "date": "2015-01-01" } 

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

PUT my_index/_doc/3
{ "date": 1420070400001 } 

GET my_index/_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.

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
{
  "mappings": {
    "_doc": {
      "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).

« Boolean datatype Geo-point datatype »

Date datatype

Date datatype

Multiple date formats

Parameters for date fields

Parameters for `date` fields