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

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

The `_timestamp` field, when enabled, allows a timestamp to be indexed and
stored with a document. The timestamp may be specified manually, generated
automatically, or set to a default value:

[source,js]
------------------------------------
PUT my_index
{
  "mappings": {
    "my_type": {
      "_timestamp": { <1>
        "enabled": true
      }
    }
  }
}

PUT my_index/my_type/1?timestamp=2015-01-01 <2>
{ "text": "Timestamp as a formatted date" }

PUT my_index/my_type/2?timestamp=1420070400000 <3>
{ "text": "Timestamp as milliseconds since the epoch" }

PUT my_index/my_type/3 <4>
{ "text": "Autogenerated timestamp set to now()" }

------------------------------------
// AUTOSENSE

<1> Enable the `_timestamp` field with default settings.
<2> Set the timestamp manually with a formatted date.
<3> Set the timestamp with milliseconds since the epoch.
<4> Auto-generates a timestamp with <<date-math,now()>>.

The behaviour of the `_timestamp` field can be configured with the following parameters:

`default`::

    A default value to be used if none is provided.  Defaults to <<date-math,now()>>.

`format`::

    The <<mapping-date-format,date format>> (or formats) to use when parsing timestamps.  Defaults to `epoch_millis||strictDateOptionalTime`.

`ignore_missing`::

    If `true` (default), replace missing timestamps with the `default` value.  If `false`, throw an exception.


The value of the `_timestamp` field is accessible in queries, aggregations, scripts,
and when sorting:

[source,js]
--------------------------
GET my_index/_search
{
  "query": {
    "range": {
      "_timestamp": { <1>
        "gte": "2015-01-01"
      }
    }
  },
  "aggs": {
    "Timestamps": {
      "terms": {
        "field": "_timestamp", <2>
        "size": 10
      }
    }
  },
  "sort": [
    {
      "_timestamp": { <3>
        "order": "desc"
      }
    }
  ],
  "script_fields": {
    "Timestamp": {
      "script": "doc['_timestamp']" <4>
    }
  }
}
--------------------------
// AUTOSENSE

<1> Querying on the `_timestamp` field
<2> Aggregating on the `_timestamp` field
<3> Sorting on the `_timestamp` field
<4> Accessing the `_timestamp` field in scripts (inline scripts must be <<enable-dynamic-scripting,enabled>> for this example to work)