239 lines
11 KiB
Plaintext
239 lines
11 KiB
Plaintext
[[mapping-date-format]]
|
|
== Date Format
|
|
|
|
In JSON documents, dates are represented as strings. Elasticsearch uses a set
|
|
of pre-configured format to recognize and convert those, but you can change the
|
|
defaults by specifying the `format` option when defining a `date` type, or by
|
|
specifying `dynamic_date_formats` in the `root object` mapping (which will
|
|
be used unless explicitly overridden by a `date` type). There are built in
|
|
formats supported, as well as complete custom one.
|
|
|
|
The parsing of dates uses http://www.joda.org/joda-time/[Joda]. The
|
|
default date parsing used if no format is specified is
|
|
http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateOptionalTimeParser--[ISODateTimeFormat.dateOptionalTimeParser].
|
|
|
|
An extension to the format allow to define several formats using `||`
|
|
separator. This allows to define less strict formats that can be used,
|
|
for example, the `yyyy/MM/dd HH:mm:ss||yyyy/MM/dd` format will parse
|
|
both `yyyy/MM/dd HH:mm:ss` and `yyyy/MM/dd`. The first format will also
|
|
act as the one that converts back from milliseconds to a string
|
|
representation.
|
|
|
|
[float]
|
|
[[date-math]]
|
|
=== Date Math
|
|
|
|
The `date` type supports using date math expression when using it in a
|
|
query/filter (mainly makes sense in `range` query/filter).
|
|
|
|
The expression starts with an "anchor" date, which can be either `now`
|
|
or a date string (in the applicable format) ending with `||`. It can
|
|
then follow by a math expression, supporting `+`, `-` and `/`
|
|
(rounding). The units supported are `y` (year), `M` (month), `w` (week),
|
|
`d` (day), `h` (hour), `m` (minute), and `s` (second).
|
|
|
|
Here are some samples: `now+1h`, `now+1h+1m`, `now+1h/d`,
|
|
`2012-01-01||+1M/d`.
|
|
|
|
When doing `range` type searches with rounding, the value parsed
|
|
depends on whether the end of the range is inclusive or exclusive, and
|
|
whether the beginning or end of the range. Rounding up moves to the
|
|
last millisecond of the rounding scope, and rounding down to the
|
|
first millisecond of the rounding scope. The semantics work as follows:
|
|
* `gt` - round up, and use > that value (`2014-11-18||/M` becomes `2014-11-30T23:59:59.999`, ie excluding the entire month)
|
|
* `gte` - round D down, and use >= that value (`2014-11-18||/M` becomes `2014-11-01`, ie including the entire month)
|
|
* `lt` - round D down, and use < that value (`2014-11-18||/M` becomes `2014-11-01`, ie excluding the entire month)
|
|
* `lte` - round D up, and use <= that value(`2014-11-18||/M` becomes `2014-11-30T23:59:59.999`, ie including the entire month)
|
|
|
|
[float]
|
|
[[built-in]]
|
|
=== Built In Formats
|
|
|
|
Most of the below dates have a `strict` companion dates, which means, that
|
|
year, month and day parts of the week must have prepending zeros in order
|
|
to be valid. This means, that a date like `5/11/1` would not be valid, but
|
|
you would need to specify the full date, which would be `2005/11/01` in this
|
|
example. So instead of `date_optional_time` you would need to specify
|
|
`strict_date_optional_time`.
|
|
|
|
The following tables lists all the defaults ISO formats supported:
|
|
|
|
[cols="<,<",options="header",]
|
|
|=======================================================================
|
|
|Name |Description
|
|
|`basic_date`|A basic formatter for a full date as four digit year, two
|
|
digit month of year, and two digit day of month (yyyyMMdd).
|
|
|
|
|`basic_date_time`|A basic formatter that combines a basic date and time,
|
|
separated by a 'T' (yyyyMMdd'T'HHmmss.SSSZ).
|
|
|
|
|`basic_date_time_no_millis`|A basic formatter that combines a basic date
|
|
and time without millis, separated by a 'T' (yyyyMMdd'T'HHmmssZ).
|
|
|
|
|`basic_ordinal_date`|A formatter for a full ordinal date, using a four
|
|
digit year and three digit dayOfYear (yyyyDDD).
|
|
|
|
|`basic_ordinal_date_time`|A formatter for a full ordinal date and time,
|
|
using a four digit year and three digit dayOfYear
|
|
(yyyyDDD'T'HHmmss.SSSZ).
|
|
|
|
|`basic_ordinal_date_time_no_millis`|A formatter for a full ordinal date
|
|
and time without millis, using a four digit year and three digit
|
|
dayOfYear (yyyyDDD'T'HHmmssZ).
|
|
|
|
|`basic_time`|A basic formatter for a two digit hour of day, two digit
|
|
minute of hour, two digit second of minute, three digit millis, and time
|
|
zone offset (HHmmss.SSSZ).
|
|
|
|
|`basic_time_no_millis`|A basic formatter for a two digit hour of day,
|
|
two digit minute of hour, two digit second of minute, and time zone
|
|
offset (HHmmssZ).
|
|
|
|
|`basic_t_time`|A basic formatter for a two digit hour of day, two digit
|
|
minute of hour, two digit second of minute, three digit millis, and time
|
|
zone off set prefixed by 'T' ('T'HHmmss.SSSZ).
|
|
|
|
|`basic_t_time_no_millis`|A basic formatter for a two digit hour of day,
|
|
two digit minute of hour, two digit second of minute, and time zone
|
|
offset prefixed by 'T' ('T'HHmmssZ).
|
|
|
|
|`basic_week_date`|A basic formatter for a full date as four digit
|
|
weekyear, two digit week of weekyear, and one digit day of week
|
|
(xxxx'W'wwe). `strict_basic_week_date` is supported.
|
|
|
|
|`basic_week_date_time`|A basic formatter that combines a basic weekyear
|
|
date and time, separated by a 'T' (xxxx'W'wwe'T'HHmmss.SSSZ).
|
|
`strict_basic_week_date_time` is supported.
|
|
|
|
|`basic_week_date_time_no_millis`|A basic formatter that combines a basic
|
|
weekyear date and time without millis, separated by a 'T'
|
|
(xxxx'W'wwe'T'HHmmssZ). `strict_week_date_time` is supported.
|
|
|
|
|`date`|A formatter for a full date as four digit year, two digit month
|
|
of year, and two digit day of month (yyyy-MM-dd). `strict_date` is supported.
|
|
_
|
|
|`date_hour`|A formatter that combines a full date and two digit hour of
|
|
day. strict_date_hour` is supported.
|
|
|
|
|
|
|`date_hour_minute`|A formatter that combines a full date, two digit hour
|
|
of day, and two digit minute of hour. strict_date_hour_minute` is supported.
|
|
|
|
|`date_hour_minute_second`|A formatter that combines a full date, two
|
|
digit hour of day, two digit minute of hour, and two digit second of
|
|
minute. `strict_date_hour_minute_second` is supported.
|
|
|
|
|`date_hour_minute_second_fraction`|A formatter that combines a full
|
|
date, two digit hour of day, two digit minute of hour, two digit second
|
|
of minute, and three digit fraction of second
|
|
(yyyy-MM-dd'T'HH:mm:ss.SSS). `strict_date_hour_minute_second_fraction` is supported.
|
|
|
|
|`date_hour_minute_second_millis`|A formatter that combines a full date,
|
|
two digit hour of day, two digit minute of hour, two digit second of
|
|
minute, and three digit fraction of second (yyyy-MM-dd'T'HH:mm:ss.SSS).
|
|
`strict_date_hour_minute_second_millis` is supported.
|
|
|
|
|`date_optional_time`|a generic ISO datetime parser where the date is
|
|
mandatory and the time is optional. `strict_date_optional_time` is supported.
|
|
|
|
|`date_time`|A formatter that combines a full date and time, separated by
|
|
a 'T' (yyyy-MM-dd'T'HH:mm:ss.SSSZZ). `strict_date_time` is supported.
|
|
|
|
|`date_time_no_millis`|A formatter that combines a full date and time
|
|
without millis, separated by a 'T' (yyyy-MM-dd'T'HH:mm:ssZZ).
|
|
`strict_date_time_no_millis` is supported.
|
|
|
|
|`hour`|A formatter for a two digit hour of day. `strict_hour` is supported.
|
|
|
|
|`hour_minute`|A formatter for a two digit hour of day and two digit
|
|
minute of hour. `strict_hour_minute` is supported.
|
|
|
|
|`hour_minute_second`|A formatter for a two digit hour of day, two digit
|
|
minute of hour, and two digit second of minute.
|
|
`strict_hour_minute_second` is supported.
|
|
|
|
|`hour_minute_second_fraction`|A formatter for a two digit hour of day,
|
|
two digit minute of hour, two digit second of minute, and three digit
|
|
fraction of second (HH:mm:ss.SSS).
|
|
`strict_hour_minute_second_fraction` is supported.
|
|
|
|
|`hour_minute_second_millis`|A formatter for a two digit hour of day, two
|
|
digit minute of hour, two digit second of minute, and three digit
|
|
fraction of second (HH:mm:ss.SSS).
|
|
`strict_hour_minute_second_millis` is supported.
|
|
|
|
|`ordinal_date`|A formatter for a full ordinal date, using a four digit
|
|
year and three digit dayOfYear (yyyy-DDD). `strict_ordinal_date` is supported.
|
|
|
|
|`ordinal_date_time`|A formatter for a full ordinal date and time, using
|
|
a four digit year and three digit dayOfYear (yyyy-DDD'T'HH:mm:ss.SSSZZ).
|
|
`strict_ordinal_date_time` is supported.
|
|
|
|
|`ordinal_date_time_no_millis`|A formatter for a full ordinal date and
|
|
time without millis, using a four digit year and three digit dayOfYear
|
|
(yyyy-DDD'T'HH:mm:ssZZ).
|
|
`strict_ordinal_date_time_no_millis` is supported.
|
|
|
|
|`time`|A formatter for a two digit hour of day, two digit minute of
|
|
hour, two digit second of minute, three digit fraction of second, and
|
|
time zone offset (HH:mm:ss.SSSZZ). `strict_time` is supported.
|
|
|
|
|`time_no_millis`|A formatter for a two digit hour of day, two digit
|
|
minute of hour, two digit second of minute, and time zone offset
|
|
(HH:mm:ssZZ). `strict_time_no_millis` is supported.
|
|
|
|
|`t_time`|A formatter for a two digit hour of day, two digit minute of
|
|
hour, two digit second of minute, three digit fraction of second, and
|
|
time zone offset prefixed by 'T' ('T'HH:mm:ss.SSSZZ).
|
|
`strict_t_time` is supported.
|
|
|
|
|`t_time_no_millis`|A formatter for a two digit hour of day, two digit
|
|
minute of hour, two digit second of minute, and time zone offset
|
|
prefixed by 'T' ('T'HH:mm:ssZZ). `strict_t_time_no_millis` is supported.
|
|
|
|
|`week_date`|A formatter for a full date as four digit weekyear, two
|
|
digit week of weekyear, and one digit day of week (xxxx-'W'ww-e).
|
|
`strict_week_date` is supported.
|
|
|
|
|`week_date_time`|A formatter that combines a full weekyear date and
|
|
time, separated by a 'T' (xxxx-'W'ww-e'T'HH:mm:ss.SSSZZ).
|
|
`strict_week_date_time` is supported.
|
|
|
|
|`week_date_time_no_millis`|A formatter that combines a full weekyear date
|
|
and time without millis, separated by a 'T' (xxxx-'W'ww-e'T'HH:mm:ssZZ).
|
|
`strict_week_date_time` is supported.
|
|
|
|
|`weekyear`|A formatter for a four digit weekyear. `strict_week_year` is supported.
|
|
|
|
|`weekyear_week`|A formatter for a four digit weekyear and two digit week
|
|
of weekyear. `strict_weekyear_week` is supported.
|
|
|
|
|`weekyear_week_day`|A formatter for a four digit weekyear, two digit week
|
|
of weekyear, and one digit day of week. `strict_weekyear_week_day` is supported.
|
|
|
|
|`year`|A formatter for a four digit year. `strict_year` is supported.
|
|
|
|
|`year_month`|A formatter for a four digit year and two digit month of
|
|
year. `strict_year_month` is supported.
|
|
|
|
|`year_month_day`|A formatter for a four digit year, two digit month of
|
|
year, and two digit day of month. `strict_year_month_day` is supported.
|
|
|
|
|`epoch_second`|A formatter for the number of seconds since the epoch.
|
|
Note, that this timestamp allows a max length of 10 chars, so dates
|
|
older than 1653 and 2286 are not supported. You should use a different
|
|
date formatter in that case.
|
|
|
|
|`epoch_millis`|A formatter for the number of milliseconds since the epoch.
|
|
Note, that this timestamp allows a max length of 13 chars, so dates
|
|
older than 1653 and 2286 are not supported. You should use a different
|
|
date formatter in that case.
|
|
|=======================================================================
|
|
|
|
[float]
|
|
[[custom]]
|
|
=== Custom Format
|
|
|
|
Allows for a completely customizable date format explained
|
|
http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html[here].
|