Docs Home → MongoDB Manual

Set up Automatic Removal for Time Series Collections (TTL)

On this page

When you create a time series collection, you can set up automatic removal of documents older than a specified number of seconds by using the expireAfterSeconds parameter:

db.createCollection(
    "weather24h",
    {
       timeseries: {
          timeField: "timestamp",
          metaField: "metadata",
          granularity: "hours"
       },
       expireAfterSeconds: 86400
    }
)

The expiration threshold is the timeField field value plus the specified number of seconds. Consider the following document in the weather24h collection:

{
   "metadata": {"sensorId": 5578, "type": "temperature"},
   "timestamp": ISODate("2021-05-18T10:00:00.000Z"),
   "temp": 12
}

The document would expire from the database at "2021-05-19T10:00:00.000Z". Once all documents in a bucket are expired, the background task that removes expired buckets removes the bucket during the next run. See Timing of Delete Operations for more information.

Enable Automatic Removal on a Collection

To enable automatic removal of documents for an existing time series collection, issue the following collMod command:

db.runCommand({
   collMod: "weather24h",
   expireAfterSeconds: 604801
})

Change the expireAfterSeconds Parameter

To change the expireAfterSeconds parameter value, issue the following collMod command:

db.runCommand({
   collMod: "weather24h",
   expireAfterSeconds: 604801
})

Retrieve the Current Value of expireAfterSeconds

To retrieve the current value of expireAfterSeconds, use the listCollections command:

db.runCommand( { listCollections: 1 } )

The result document contains a document for the time series collection which contains the options.expireAfterSeconds field.

{
    cursor: {
       id: <number>,
       ns: 'test.$cmd.listCollections',
       firstBatch: [
         {
            name: <string>,
            type: 'timeseries',
            options: {
               expireAfterSeconds: <number>,
               timeseries: { ... }
            },
            ...
         },
         ...
       ]
    }
 }

Disable Automatic Removal

To disable automatic removal, use the collMod command to set expireAfterSeconds to off:

db.runCommand({
    collMod: "weather24h",
    expireAfterSeconds: "off"
})

Behavior

Timing of Delete Operations

MongoDB doesn't guarantee that expired data will be deleted immediately upon expiration. Once all documents in a bucket are expired, the background task that removes expired buckets removes the bucket during the next run. The maximum span of time that a single bucket is allowed to cover is controlled by the granularity of the time series collection:

granularityCovered Time Span
"seconds" (default)one hour
"minutes"24 hours
"hours"30 days

The background task that removes expired buckets runs every 60 seconds. Therefore, documents may remain in a collection during the period between the expiration of the document, the expiration of all other documents in the bucket and the running of the background task.

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