TTL Indexes

TTL indexes are special single-field indexes that MongoDB can use toautomatically remove documents from a collection after a certain amountof time or at a specific clock time. Data expiration is useful for certain types of informationlike machine generated event data, logs, and session information thatonly need to persist in a database for a finite amount of time.

To create a TTL index, use the db.collection.createIndex()method with the expireAfterSeconds option on a field whose value iseither a date or an array thatcontains date values.

For example, to create a TTL index on the lastModifiedDate field ofthe eventlog collection, use the following operation in themongo shell:

  1. db.eventlog.createIndex( { "lastModifiedDate": 1 }, { expireAfterSeconds: 3600 } )

Behavior

Expiration of Data

TTL indexes expire documents after the specified number of seconds haspassed since the indexed field value; i.e. the expiration threshold isthe indexed field value plus the specified number of seconds.

If the field is an array, and there are multiple date values in theindex, MongoDB uses lowest (i.e. earliest) date value in the array tocalculate the expiration threshold.

If the indexed field in a document is not a dateor an array that holds a date value(s), the document will not expire.

If a document does not contain the indexed field, the document will notexpire.

Delete Operations

A background thread in mongod reads the values in the indexand removes expired documents from the collection.

When the TTL thread is active, you will see delete operations in theoutput of db.currentOp() or in the data collected by thedatabase profiler.

Timing of the Delete Operation

For feature compatibility version (fcv) "4.2",MongoDB begins removing expired documents as soon as theindex finishes building.

For feature compatibility version (fcv) "4.0",the timing of delete operations depends on the index build type:

  • With foreground index builds, MongoDB can begin removingexpired documents only after the build completes.
  • With background index builds, MongoDB can begin removingexpired documents as soon as the they are processed by the build.

For more information on the index build process, seeIndex Builds on Populated Collections.

The TTL index does not guarantee that expired data will be deletedimmediately upon expiration. There may be a delay between the time adocument expires and the time that MongoDB removes the document fromthe database.

The background task that removes expired documents runs every 60seconds. As a result, documents may remain in a collection during theperiod between the expiration of the document and the running of thebackground task.

Because the duration of the removal operation depends on the workloadof your mongod instance, expired data may exist for sometime beyond the 60 second period between runs of the background task.

Replica Sets

On replica set members, the TTL background thread _only_deletes documents when a member is in state primary. The TTL backgroundthread is idle when a member is in state secondary. Secondary members replicatedeletion operations from the primary.

Support for Queries

A TTL index supports queries in the same way non-TTL indexes do.

Restrictions

  • TTL indexes are a single-field indexes. Compound indexes do not support TTL and ignore theexpireAfterSeconds option.
  • The _id field does not support TTL indexes.
  • You cannot create a TTL index on a capped collection because MongoDB cannot remove documentsfrom a capped collection.
  • You cannot use createIndex() to change thevalue of expireAfterSeconds of an existing index. Instead use thecollMod database command in conjunction with theindex collection flag. Otherwise, to change the value ofthe option of an existing index, you must drop the index first andrecreate.
  • If a non-TTL single-field index already exists for a field, youcannot create a TTL index on the same field since you cannot createindexes that have the same key specification and differ only by theoptions. To change a non-TTL single-field index to a TTL index, youmust drop the index first and recreate with theexpireAfterSeconds option.