OpenSearch/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 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]
==== 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 requires an
additional (though quite fast) parsing phase.

[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 `dateOptionalTime`. 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 disable that default value by setting `default` to `null`. It means that `timestamp` is mandatory:

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

If you don't provide any timestamp value, indexation will fail.

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, indexation will fail.