elasticsearch/docs/reference/mapping/fields/timestamp-field.asciidoc

[[mapping-timestamp-field]]
=== `_timestamp`

The `_timestamp` field allows to automatically index the timestamp of a
document. It can be provided externally via the index request or in the
`_source`. If it is not provided externally it will be automatically set
to the date the document was processed by the indexing chain.

[float]
==== enabled

By default it is disabled. In order to enable it, the following mapping
should be defined:

[source,js]
--------------------------------------------------
{
    "tweet" : {
        "_timestamp" : { "enabled" : true }
    }
}
--------------------------------------------------

[float]
==== store / index

By default the `_timestamp` field has `store` set to `false` and `index`
set to `not_analyzed`. It can be queried as a standard date field.

[float]
==== path

The `_timestamp` value can be provided as an external value when
indexing. But, it can also be automatically extracted from the document
to index based on a `path`. For example, having the following mapping:

[source,js]
--------------------------------------------------
{
    "tweet" : {
        "_timestamp" : {
            "enabled" : true,
            "path" : "post_date"
        }
    }
}
--------------------------------------------------

Will cause `2009-11-15T14:12:12` to be used as the timestamp value for:

[source,js]
--------------------------------------------------
{
    "message" : "You know, for Search",
    "post_date" : "2009-11-15T14:12:12"
}
--------------------------------------------------

Note, using `path` without explicit timestamp value provided require an
additional (though quite fast) parsing phase.

[float]
==== format

You can define the <<mapping-date-format,date
format>> used to parse the provided timestamp value. For example:

[source,js]
--------------------------------------------------
{
    "tweet" : {
        "_timestamp" : {
            "enabled" : true,
            "path" : "post_date",
            "format" : "YYYY-MM-dd"
        }
    }
}
--------------------------------------------------

Note, the default format is `dateOptionalTime`. The timestamp value will
first be parsed as a number and if it fails the format will be tried.