WARNING: Version 2.3 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« _timestamp field _type field »
Elastic Docs ›Elasticsearch Guide [2.3] ›Mapping ›Meta-Fields

_ttl field

edit

_ttl field

edit

Deprecated in 2.0.0-beta2.

The current _ttl implementation is deprecated and will be replaced with a different implementation in a future version

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.

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:

PUT my_index
{
  "mappings": {
    "my_type": {
      "_ttl": {
        "enabled": true
      }
    }
  }
}

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

PUT my_index/my_type/2 
{
  "text": "Will not expire"
}

This document will expire 10 minutes after being indexed.

This document has no TTL set and will not expire.

The expiry time is calculated as the value of the _timestamp field (or now() if the _timestamp is not enabled) plus the ttl specified in the indexing request.

Default TTL

edit

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

PUT my_index
{
  "mappings": {
    "my_type": {
      "_ttl": {
        "enabled": true,
        "default": "5m"
      }
    }
  }
}

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

PUT my_index/my_type/2 
{
  "text": "Will expire in 5 minutes"
}

This document will expire 10 minutes after being indexed.

This document has no TTL set and so will expire after the default 5 minutes.

The default value can use 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

edit

Expired documents will be automatically deleted periodically. 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 bulk request. The default value is 10000.

Note on detect_noop

edit

If an update tries to update just the _ttl without changing the _source of the document it’s expiration time won’t be updated if detect_noop is true. In 2.1 detect_noop defaults to true.

« _timestamp field _type field »