Date nanoseconds field type

This data type is an addition to the date data type. However there is an important distinction between the two. The existing date data type stores dates in millisecond resolution. The date_nanos data type stores dates in nanosecond resolution, which limits its range of dates from roughly 1970 to 2262, as dates are still stored as a long representing nanoseconds since the epoch.

Queries on nanoseconds 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.

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

  1. "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 including up to nine second fractionals or milliseconds-since-the-epoch (thus losing precision on the nano second part). Using strict_date_optional_time will format the result up to only three second fractionals. To print and parse up to nine digits of resolution, use strict_date_optional_time_nanos.

For instance:

  1. PUT my-index-000001?include_type_name=true
  2. {
  3.   "mappings": {
  4.     "_doc": {
  5.       "properties": {
  6.         "date": {
  7.           "type": "date_nanos" 
  8.         }
  9.       }
  10.     }
  11.   }
  12. }
  14. PUT my-index-000001/_doc/1
  15. { "date": "2015-01-01" } 
  17. PUT my-index-000001/_doc/2
  18. { "date": "2015-01-01T12:10:30.123456789Z" } 
  20. PUT my-index-000001/_doc/3
  21. { "date": 1420070400 } 
  23. GET my-index-000001/_search
  24. {
  25.   "sort": { "date": "asc"} 
  26. }
  28. GET my-index-000001/_search
  29. {
  30.   "script_fields" : {
  31.     "my_field" : {
  32.       "script" : {
  33.         "lang" : "painless",
  34.         "source" : "doc['date'].value.nano" 
  35.       }
  36.     }
  37.   }
  38. }
  40. GET my-index-000001/_search
  41. {
  42.   "docvalue_fields" : [
  43.     {
  44.       "field" : "date",
  45.       "format": "strict_date_time" 
  46.     }
  47.   ]
  48. }

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 nanoseconds-since-the-epoch.

Access the nanosecond part of the date in a script

Use doc value fields, which can be formatted in nanosecond resolution

You can also specify multiple date formats separated by ||. The same mapping parameters than with the date field can be used.

Limitations

Aggregations are still on millisecond resolution, even when using a date_nanos field. This limitation also affects transforms.