Expire Data from Collections by Setting TTL

This document provides an introduction to MongoDB’s “time to live”or TTL collection feature. TTL collections make it possible tostore data in MongoDB and have the mongod automaticallyremove data after a specified number of seconds or at a specific clocktime.

Data expiration is useful for some classes of information, includingmachine generated event data, logs, and session information that onlyneed to persist for a limited period of time.

A special TTL index property supports theimplementation of TTL collections. The TTL feature relies on abackground thread in mongod that reads the date-typed valuesin the index and removes expired documents from thecollection.

Procedures

To create a TTL index, use thedb.collection.createIndex() method with theexpireAfterSeconds option on a field whose value is either adate or an array that containsdate values.

Note

The TTL index is a single field index. Compound indexes do notsupport the TTL property. For more information on TTL indexes, seeTTL Indexes.

You can modify the expireAfterSeconds of an existing TTL indexusing the collMod command.

Expire Documents after a Specified Number of Seconds

To expire data after a specified number of seconds has passed since theindexed field, create a TTL index on a field that holds values of BSONdate type or an array of BSON date-typed objects and specify apositive non-zero value in the expireAfterSeconds field. A documentwill expire when the number of seconds in the expireAfterSecondsfield has passed since the time specified in its indexed field.[1]

For example, the following operation creates an index on thelog_events collection’s createdAt field and specifies theexpireAfterSeconds value of 3600 to set the expiration time tobe one hour after the time specified by createdAt.

db.log_events.createIndex( { "createdAt": 1 }, { expireAfterSeconds: 3600 } )

When adding documents to the log_events collection, set thecreatedAt field to the current time:

db.log_events.insert( {
   "createdAt": new Date(),
   "logEvent": 2,
   "logMessage": "Success!"
} )

MongoDB will automatically delete documents from the log_eventscollection when the document’s createdAt value[1] is older than the number of secondsspecified in expireAfterSeconds.

See also

$currentDate operator

Expire Documents at a Specific Clock Time

To expire documents at a specific clock time, begin by creating a TTLindex on a field that holds values of BSON date type or an array ofBSON date-typed objects and specify an expireAfterSeconds valueof 0. For each document in the collection, set the indexed datefield to a value corresponding to the time the document should expire.If the indexed date field contains a date in the past, MongoDBconsiders the document expired.

For example, the following operation creates an index on thelog_events collection’s expireAt field and specifies theexpireAfterSeconds value of 0:

db.log_events.createIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )

For each document, set the value of expireAt to correspond to thetime the document should expire. For instance, the followinginsert() operation adds a document that shouldexpire at July 22, 2013 14:00:00.

db.log_events.insert( {
   "expireAt": new Date('July 22, 2013 14:00:00'),
   "logEvent": 2,
   "logMessage": "Success!"
} )

MongoDB will automatically delete documents from the log_eventscollection when the documents’ expireAt value is older than thenumber of seconds specified in expireAfterSeconds, i.e. 0seconds older in this case. As such, the data expires at the specifiedexpireAt value.