MongoDB Time To Live (TTL) Collections

• Download source

A new feature was introduced in MongoDB 2.2: Time To Live collections. TTL collection is a collection, where documents automatically will be removed after specific period of time. The common use-case for TTL collections is to store some session information, or use it as a cache for your system. 

If you want to make your collection TTL, you should use expireAfterSeconds index option:

db.ttl.ensureIndex({"Date": 1}, {expireAfterSeconds: 300})

Restrictions

There are some restrictions on choosing TTL Index:

• you can't create TTL index if indexed field is already used in another index
• index can't have multiple fields
• indexed field should be a Date bson type

If you violate one of these rules, documents wouldn't be removed after expiration time.

How are they removed?

mongod background process keeps track on expired documents and removes them.

Lets check this out: At first, we should create an index and set expire after 10 seconds.

db.ttl_collection.ensureIndex( { "Date": 1 }, { expireAfterSeconds: 10 } )

Now lets insert a document.

db.ttl_collection.insert({"Date" : new Date()})

So we think this document should be removed after 10 seconds. I've checked this on my computer a few times and results were very different. Sometimes mongod removes my document after 18 seconds, sometimes after 40 seconds. Why? We told MongoDB that we want to remove them after 10 seconds, but MongoDB does this at different time.

For example, in this case it takes about 45 seconds:

This happens because mongod background task checks expired document once a minute. So there always will be a little difference in expiration time that you set and a real time elapsed before they are removed. But it will be not more than about 1 minute. It can depend on workload of your MongoDB instance.

Can we set TTL index to existing collection?

Yes, you can. Documents which were added to this collection before setting TTL index will be removed according to their Date field:

Can we prevent some documents from removing?

Yes, you can do it in 2 ways:

• always update documents TTL field date before it will be removed
• set a non-date value to TTL field

For example, if I set Date field to null, it never will be removed:

Conclusion

Time To Live collection is a great feature of MongoDB 2.2. But you need to consider that documents may remain in collection after they expire but before background process runs.