Date field type
editDate field type
editJSON 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).
Internally, dates are converted to UTC (if the time-zone is specified) and stored as a long number representing milliseconds-since-the-epoch.
Use the date_nanos field type if a nanosecond resolution is expected.
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:
response = client.indices.create( index: 'my-index-000001', body: { mappings: { properties: { date: { type: 'date' } } } } ) puts response response = client.indices.create( index: 'my-index-000001', id: 1, body: { date: '2015-01-01' } ) puts response response = client.indices.create( index: 'my-index-000001', id: 2, body: { date: '2015-01-01T12:10:30Z' } ) puts response response = client.indices.create( index: 'my-index-000001', id: 3, body: { date: 1_420_070_400_001 } ) puts response response = client.indices.create( index: 'my-index-000001', body: { sort: { date: 'asc' } } ) puts response
{ res, err := es.Indices.Create( "my-index-000001", es.Indices.Create.WithBody(strings.NewReader(`{ "mappings": { "properties": { "date": { "type": "date" } } } }`)), ) fmt.Println(res, err) } { res, err := es.Index( "my-index-000001", strings.NewReader(`{ "date": "2015-01-01" } `), es.Index.WithDocumentID("1"), es.Index.WithPretty(), ) fmt.Println(res, err) } { res, err := es.Index( "my-index-000001", strings.NewReader(`{ "date": "2015-01-01T12:10:30Z" } `), es.Index.WithDocumentID("2"), es.Index.WithPretty(), ) fmt.Println(res, err) } { res, err := es.Index( "my-index-000001", strings.NewReader(`{ "date": 1420070400001 } `), es.Index.WithDocumentID("3"), es.Index.WithPretty(), ) fmt.Println(res, err) } { res, err := es.Search( es.Search.WithIndex("my-index-000001"), es.Search.WithBody(strings.NewReader(`{ "sort": { "date": "asc" } }`)), es.Search.WithPretty(), ) fmt.Println(res, err) }
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 |
|
This document uses a plain date. |
|
This document includes a time. |
|
This document uses milliseconds-since-the-epoch. |
|
Note that the |
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 they should be avoided.
Multiple date formats
editMultiple 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.
response = client.indices.create( index: 'my-index-000001', body: { mappings: { properties: { date: { type: 'date', format: 'yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis' } } } } ) puts response
res, err := es.Indices.Create( "my-index-000001", es.Indices.Create.WithBody(strings.NewReader(`{ "mappings": { "properties": { "date": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis" } } } }`)), ) fmt.Println(res, err)
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
editThe following parameters are accepted by date
fields:
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 |
|
The date format(s) that can be parsed. Defaults to
|
|
|
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
|
If |
|
Should the field be quickly searchable? Accepts |
|
Accepts a date value in one of the configured |
|
|
Defines what to do if the script defined by the |
|
If this parameter is set, then the field will index values generated by this script, rather than reading the values directly from the source. If a value is set for this field on the input document, then the document will be rejected with an error. Scripts are in the same format as their runtime equivalent, and should emit long-valued timestamps. |
Whether the field value should be stored and retrievable separately from
the |
|
Metadata about the field. |
Epoch seconds
editIf 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", "_score": 1.0, "fields": { "date": ["2021-04-13T13:51:38.000Z"] } } ] } }
Synthetic _source
[preview]
This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
editdate
fields support synthetic _source
in their
default configuration. Synthetic _source
cannot be used together with
copy_to
, ignore_malformed
set to true
or with doc_values
disabled.
Synthetic source always sorts date
fields. For example:
PUT idx { "mappings": { "_source": { "mode": "synthetic" }, "properties": { "date": { "type": "date" } } } } PUT idx/_doc/1 { "date": ["2015-01-01T12:10:30Z", "2014-01-01T12:10:30Z"] }
Will become:
{ "date": ["2014-01-01T12:10:30.000Z", "2015-01-01T12:10:30.000Z"] }