<commit_before>[[mapping-date-format]]
=== `format`

In JSON documents, dates are represented as strings. Elasticsearch uses a set
of preconfigured formats to recognize and parse these strings into a long
value representing _milliseconds-since-the-epoch_ in UTC.

Besides the <<built-in-date-formats,built-in formats>>, your own
<<custom-date-formats,custom formats>> can be specified using the familiar
`yyyy/MM/dd` syntax:

[source,console]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "properties": {
      "date": {
        "type":   "date",
        "format": "yyyy-MM-dd"
      }
    }
  }
}
--------------------------------------------------

Many APIs which support date values also support <<date-math,date math>>
expressions, such as `now-1m/d` -- the current time, minus one month, rounded
down to the nearest day.

[[custom-date-formats]]
==== Custom date formats

Completely customizable date formats are supported.  The syntax for these is explained
https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter docs].

[[built-in-date-formats]]
==== Built In Formats

Most of the below formats have a `strict` companion format, which means that
year, month and day parts of the week must use respectively 4, 2 and 2 digits
exactly, potentially prepending zeros. For instance a date like `5/11/1` would
be considered invalid and would need to be rewritten to `2005/11/01` to be
accepted by the date parser.

To use them, you need to prepend `strict_` to the name of the date format, for
instance `strict_date_optional_time` instead of `date_optional_time`.

These strict date formats are especially useful when
<<date-detection,date fields are dynamically mapped>> in order to make sure to
not accidentally map irrelevant strings as dates.

The following tables lists all the defaults ISO formats supported:

`epoch_millis`::

    A formatter for the number of milliseconds since the epoch. Note, that
    this timestamp is subject to the limits of a Java `Long.MIN_VALUE` and
    `Long.MAX_VALUE`.

`epoch_second`::

    A formatter for the number of seconds since the epoch. Note, that this
    timestamp is subject to the limits of a Java `Long.MIN_VALUE` and `Long.
    MAX_VALUE` divided by 1000 (the number of milliseconds in a second).

[[strict-date-time]]`date_optional_time` or `strict_date_optional_time`::

    A generic ISO datetime parser where the date, in `year_month_day format`, is
    mandatory and the time, separated by `T`, is optional.
    Examples: `yyyy-MM-dd'T'HH:mm:ss.SSSZ` or  `yyyy-MM-dd`.

`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<commit_msg>[DOCS] Fix typo in mapping date format docs<commit_after>[[mapping-date-format]]
=== `format`

In JSON documents, dates are represented as strings. Elasticsearch uses a set
of preconfigured formats to recognize and parse these strings into a long
value representing _milliseconds-since-the-epoch_ in UTC.

Besides the <<built-in-date-formats,built-in formats>>, your own
<<custom-date-formats,custom formats>> can be specified using the familiar
`yyyy/MM/dd` syntax:

[source,console]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "properties": {
      "date": {
        "type":   "date",
        "format": "yyyy-MM-dd"
      }
    }
  }
}
--------------------------------------------------

Many APIs which support date values also support <<date-math,date math>>
expressions, such as `now-1m/d` -- the current time, minus one month, rounded
down to the nearest day.

[[custom-date-formats]]
==== Custom date formats

Completely customizable date formats are supported.  The syntax for these is explained
https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[DateTimeFormatter docs].

[[built-in-date-formats]]
==== Built In Formats

Most of the below formats have a `strict` companion format, which means that
year, month and day parts of the week must use respectively 4, 2 and 2 digits
exactly, potentially prepending zeros. For instance a date like `5/11/1` would
be considered invalid and would need to be rewritten to `2005/11/01` to be
accepted by the date parser.

To use them, you need to prepend `strict_` to the name of the date format, for
instance `strict_date_optional_time` instead of `date_optional_time`.

These strict date formats are especially useful when
<<date-detection,date fields are dynamically mapped>> in order to make sure to
not accidentally map irrelevant strings as dates.

The following tables lists all the defaults ISO formats supported:

`epoch_millis`::

    A formatter for the number of milliseconds since the epoch. Note, that
    this timestamp is subject to the limits of a Java `Long.MIN_VALUE` and
    `Long.MAX_VALUE`.

`epoch_second`::

    A formatter for the number of seconds since the epoch. Note, that this
    timestamp is subject to the limits of a Java `Long.MIN_VALUE` and `Long.
    MAX_VALUE` divided by 1000 (the number of milliseconds in a second).

[[strict-date-time]]`date_optional_time` or `strict_date_optional_time`::

    A generic ISO datetime parser where the date, in `year_month_day` format, is
    mandatory and the time, separated by `T`, is optional.
    Examples: `yyyy-MM-dd'T'HH:mm:ss.SSSZ` or  `yyyy-MM-dd`.

`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
{'fraction_non_alphanumeric': 0.11251798561151079, 'fraction_numerical': 0.0060431654676258995, 'mean_word_length': 3.525390625, 'pattern_counts': {'":': 10, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '361261', 'n_tokens_mistral': 2098, 'n_tokens_neox': 1999, 'n_words': 850}