- Application Development >
- Expire Data from Collections by Setting TTL
Expire Data from Collections by Setting TTL¶
On this page
New in version 2.2.
This document provides an introduction to MongoDB’s “time to live”
or “TTL” collection feature. Implemented as a special index
type, TTL collections make it possible to store data in MongoDB and
have the mongod
automatically remove data after a specified
period of time. This is ideal for some types of information like
machine generated event data, logs, and session information that only
need to persist in a database for a limited period of time.
Background¶
Collections expire by way of a special index of a field with date
values in conjunction with a background thread in mongod
that regularly removes expired documents from the
collection. You can use this feature to expire data from
replica sets and sharded clusters.
Use the expireAfterSeconds
option to the ensureIndex
method in conjunction with a TTL value
in seconds to create an expiring collection. TTL collections set the
usePowerOf2Sizes
collection flag, which means MongoDB must
allocate more disk space relative to data size. This approach helps
mitigate the possibility of storage fragmentation caused by frequent
delete operations and leads to more predictable storage use patterns.
Note
When the TTL thread is active, you will see a delete operation in the output of
db.currentOp()
or in the data collected by the
database profiler.
Constraints¶
Consider the following limitations:
- the indexed field must be a date BSON type. If the field does not have a date type, the data will not expire.
- you cannot create this index on the
_id
field, or a field that already has an index. - the TTL index may not be compound (may not have multiple fields).
- if the field holds an array, and there are multiple date-typed data in the index, the document will expire when the lowest (i.e. earliest) matches the expiration threshold.
- you cannot use a TTL index on a capped collection, because MongoDB cannot remove documents from a capped collection.
Note
TTL indexes expire data by removing documents in a background task that runs every 60 seconds. As a result, the TTL index provides no guarantees that expired documents will not exist in the collection. Consider that:
- Documents may remain in a collection after they expire and before the background process runs.
- The duration of the removal operations depend on the workload of
your
mongod
instance.
Enabling a TTL for a Collection¶
To set a TTL on the collection “log.events
” for one hour use the
following command at the mongo
shell:
The status
field must hold date/time information. MongoDB will
automatically delete documents from this collection once the value of
status
is one or more hours old.
Replication¶
The TTL background thread only runs on primary members of replica sets. Secondaries members will replicate deletion operations from the primaries.