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

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

The `_timestamp` field allows to automatically index the timestamp of a
document. If it is not provided it will be automatically set
to a <<mapping-timestamp-field-default,default date>>.

[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]
[[mapping-timestamp-field-format]]
==== 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 `epoch_millis||strictDateOptionalTime`. The timestamp value will
first be parsed as a number and if it fails the format will be tried.

[float]
[[mapping-timestamp-field-default]]
==== default

You can define a default value for when timestamp is not provided
within the index request or in the `_source` document.

By default, the default value is `now` which means the date the document was processed by the indexing chain.

You can reject documents which do not provide a `timestamp` value by setting `ignore_missing` to false (default to `true`):

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

You can also set the default value to any date respecting <<mapping-timestamp-field-format,timestamp format>>:

[source,js]
--------------------------------------------------
{
    "tweet" : {
        "_timestamp" : {
            "enabled" : true,
            "format" : "YYYY-MM-dd",
            "default" : "1970-01-01"
        }
    }
}
--------------------------------------------------

If you don't provide any timestamp value, _timestamp will be set to this default value.

In elasticsearch 1.4, we allowed setting explicitly `"default":null` which is not possible anymore
as we added a new `ignore_missing` setting.
When reading an index created with elasticsearch 1.4 and using this, we automatically update it by
removing `"default": null` and setting `"ignore_missing": false`