Expire Data from Collections by Setting TTL

Expire Documents after a Specified Number of Seconds

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

The TTL index expireAfterSeconds value must be within 0 and 2147483647 inclusive.

For example, the following operation creates an index on the log_events collection's createdAt field and specifies the expireAfterSeconds value of 10 to set the expiration time to be ten seconds after the time specified by createdAt.

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

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

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

MongoDB will automatically delete documents from the log_events collection when the document's createdAt value [1] is older than the number of seconds specified in expireAfterSeconds.

Expire Documents at a Specific Clock Time

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

For example, the following operation creates an index on the log_events collection's expireAt field and specifies the expireAfterSeconds value of 0:

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

For each document, set the value of expireAt to correspond to the time the document should expire. For example, the following insertOne() operation adds a document that expires at July 22, 2013 14:00:00.

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

MongoDB will automatically delete documents from the log_events collection when the documents' expireAt value is older than the number of seconds specified in expireAfterSeconds, i.e. 0 seconds older in this case. As such, the data expires at the specified expireAt value.

Indexes Configured Using NaN

Do not set expireAfterSeconds to NaN in your TTL index configuration.

Prior to MongoDB 5.0, when a TTL index has expireAfterSeconds set to NaN, MongoDB logs an error and does not remove any records.

From MongoDB 5.0.0 - 5.0.13 (and 6.0.0 - 6.0.1), NaN is treated as 0. If a TTL index is configured with expireAfterSeconds set to NaN, all TTL-indexed documents expire immediately.

Starting in MongoDB 5.0.14 (and 6.0.2), the server will not use TTL indexes that have expireAfterSeconds set to NaN.

However, there are still some situations which may result in unexpected behavior. Documents may expire:

• During an initial sync to an earlier version from MongoDB 5.0.0 - 5.0.13 (or 6.0.0 - 6.0.1).

• When upgrading from an earlier version to MongoDB 5.0.0 - 5.0.13.

• When restoring a collection from a pre-5.0 mongodump into a MongoDB 5.0.0 - 5.0.13 (or 6.0.0 - 6.0.1) instance.

To avoid problems, either drop or correct any misconfigured TTL indexes.

function getNaNIndexes() {
  const nan_index = [];
  const dbs = db.adminCommand({ listDatabases: 1 }).databases;
  dbs.forEach((d) => {
    const listCollCursor = db
      .getSiblingDB(d.name)
      .runCommand({ listCollections: 1 }).cursor;
    const collDetails = {
      db: listCollCursor.ns.split(".$cmd")[0],
      colls: listCollCursor.firstBatch.map((c) => c.name),
    };
    collDetails.colls.forEach((c) =>
      db
        .getSiblingDB(collDetails.db)
        .getCollection(c)
        .getIndexes()
        .forEach((entry) => {
          if (Object.is(entry.expireAfterSeconds, NaN)) {
            nan_index.push({ ns: `${collDetails.db}.${c}`, index: entry });
          }
        })
    );
  });
  return nan_index;
};
getNaNIndexes();