Let MongoDB Clean Up After Itself: A Complete Guide to TTL Indexes

In a world drowning in logs, every millisecond counts.

Have you ever:

• Struggled with a bloated MongoDB collection full of outdated logs?
• Set cron jobs to purge old data manually?
• Wished MongoDB could just “clean itself”?

Good news. It can.

With TTL (Time-To-Live) Indexes, MongoDB does the cleanup for you quietly, efficiently, and automatically.In this blog, we’ll explore how TTL indexes work, how to set them up, and how they silently clean up stale data while you focus on what matters most.

What’s a TTL Index?

A TTL index in MongoDB is a type of index that automatically removes documents from a collection after a certain period. Perfect for:

• Application logs
• User sessions or tokens
• Expired notifications
• Cache data

Why use it?   

• Automatic cleanup
• Saves storage
• Boosts query performance
• Zero scripting or cron jobs

How TTL Indexes Work

MongoDB runs a background job every 60 seconds, known as the TTL monitor. It checks documents in collections with TTL indexes and deletes those whose timestamp exceeds the specified age.

Internal Flow – TTL Operation Logic

To better understand this, here’s a visual flowchart of how MongoDB handles TTL expiration:

Flow Description:

1. Index Creation: TTL index is created on a date field (e.g., createdAt) with a threshold (e.g., 1 month).
2. Background Monitor: Every 60 seconds, MongoDB checks the timestamp of each document.
3. Evaluation:     If a document is older than the TTL, it is deleted.

                                 If it’s still within the threshold, it’s retained.                                                                                                                                                                                                                                                                                                                                             

This cycle repeats automatically—no developer effort needed.

Step-by-Step: Setting Up a TTL Index

Step 1: Insert a Document with a Timestamp

db.logs.insertOne({
  message: "User login",
  level: "INFO",
  createdAt: new Date()
});

Step 2: Create a TTL Index (e.g., 10 Days)

db.logs.createIndex(
  { createdAt: 1 },
  { expireAfterSeconds: 864000 } // 10 days
);

Step 3: Verify the Index

db.logs.getIndexes();

That’s it -MongoDB takes care of the rest.

Advanced Feature: Partial TTL Indexes (MongoDB 4.2)  
Introduced in MongoDB 4.2, partial TTL indexes allow you to automatically expire only a subset of documents based on a filter expression. This is particularly useful when:

• You want to delete logs from a specific sensor
• Only some records need expiry based on a condition
• You're working with time-series collections and need targeted cleanup

Example: Create a Partial TTL Index
db.eventlog.createIndex(
{ "timestamp": 1 },
{
partialFilterExpression: { "sensor": { $eq: "40.761873, -73.984287" } },
expireAfterSeconds: 3600
}
);

Only documents where sensor = "40.761873, -73.984287" will be considered for TTL expiration. Others remain untouched.

Monitoring TTL Activity: Stay Informed  
After enabling TTL indexes, it’s important to verify that they're working correctly.  

Check TTL Metrics

db.serverStatus().metrics.ttl

Sample Output

{
  "deletedDocuments": 100000,
  "passes": 60
}

deletedDocuments → Total documents auto-deleted by TTL

passes → Total scans performed by the TTL monitor thread  

The chart below visually represents the number of documents deleted by the TTL process.

Why Monitor TTL Metrics?

• Ensures that TTL deletions are happening as expected
• Detects performance bottlenecks or misconfigurations
• Helps in tuning the TTL monitor interval if needed

Adjusting TTL Monitor Frequency

MongoDB’s TTL monitor runs by default every 60 seconds, scanning for expired documents. You can tune this interval to reduce background load or delay deletions.  

To increase the interval (e.g., once per hour):

db.adminCommand({ setParameter: 1, ttlMonitorSleepSecs: 3600 });

• This sets the TTL monitor to run every 3600 seconds (1 hour).
• Use with caution—expired documents will remain longer before deletion.
• For permanent changes, add it to mongod.conf or use it in the startup command.

Important: Clean Historical Data Before Enabling TTL

If your collection already contains a large number of past (expired) records, enabling a TTL index may trigger bulk deletions, causing performance spikes.  

It’s best to manually clean old records first, especially for collections with:  
 

• High write volume
• Time-sensitive queries
• Large data sets

Real-World Impact  
We applied TTL indexes in a microservice environment logging over 3 million events/month.  

Results:

• 40% disk space savings
• Reduced index bloat
• No need for scheduled cleanup scripts
• Cleaner collections, faster queries

When Not to Use TTL?   

TTL is not suitable if:  
 

• You need soft-deletes or restore functionality
• Data must be archived for compliance or auditing
• Expiry conditions are dynamic or not based on a fixed timestamp

In such cases, use background jobs or ETL pipelines instead.  

Conclusion  
TTL Indexes in MongoDB are a developer’s dream for automating the cleanup of obsolete data. They’re simple, efficient, and powerful—especially for time-bound datasets like logs and cache.  
 

• Easy to implement
• Hands-free maintenance
• Boosts performance  

So stop writing cleanup scripts. Let MongoDB clean up after itself.