OpenSearch/docs/reference/mapping/fields/ttl-field.asciidoc

[[mapping-ttl-field]]
=== `_ttl` field

Some types of documents, such as session data or special offers, come with an
expiration date. The `_ttl` field allows you to specify the minimum time a
document should live, after which time the document is deleted automatically.

[TIP]
.Prefer index-per-timeframe to TTL
======================================================

With TTL , expired documents first have to be marked as deleted then later
purged from the index when segments are merged.  For append-only time-based
data such as log events, it is much more efficient to use an index-per-day /
week / month instead of TTLs.  Old log data can be removed by simply deleting
old indices.

======================================================

The `_ttl` field may be enabled as follows:

[source,js]
-------------------------------
PUT my_index
{
  "mappings": {
    "my_type": {
      "_ttl": {
        "enabled": true
      }
    }
  }
}

PUT my_index/my_type/1?ttl=10m <1>
{
  "text": "Will expire in 10 minutes"
}

PUT my_index/my_type/2 <2>
{
  "text": "Will not expire"
}
-------------------------------
// AUTOSENSE
<1> This document will expire 10 minutes after being indexed.
<2> This document has no TTL set and will not expire.

The expiry time is calculated as the value of the
<<mapping-timestamp-field,`_timestamp`>> field (or `now()` if the `_timestamp`
is not enabled) plus the `ttl` specified in the indexing request.

==== Default TTL

You can provide a default `_ttl`, which will be applied to indexing requests where the `ttl` is not specified:

[source,js]
-------------------------------
PUT my_index
{
  "mappings": {
    "my_type": {
      "_ttl": {
        "enabled": true,
        "defaut": "5m"
      }
    }
  }
}

PUT my_index/my_type/1?ttl=10m <1>
{
  "text": "Will expire in 10 minutes"
}

PUT my_index/my_type/2 <2>
{
  "text": "Will expire in 5 minutes"
}
-------------------------------
// AUTOSENSE
<1> This document will expire 10 minutes after being indexed.
<2> This document has no TTL set and so will expire after the default 5 minutes.

The `default` value can use <<time-units,time units>> like `d` for days, and
will use `ms` as the default unit if no time unit is provided.

You can dynamically update the `default` value using the put mapping
API. It won't change the `_ttl` of already indexed documents but will be
used for future documents.

==== Note on documents expiration

Expired documents will be automatically deleted periodoically. The following
settings control the expiry process:

`indices.ttl.interval`::

How often the purge process should run. Defaults to `60s`. Expired documents
may still be retrieved before they are purged.

`indices.ttl.bulk_size`::

How many deletions are handled by a single <<docs-bulk,`bulk`>> request. The
default value is `10000`.