TTL Indexes
Parent: MongoDB Indexes Deep Dive · Published reference · snapshot 2026-10-24 · skill mongodb-cohort-ebff5b8ead9e
↓ Facts as markdownall context files
Source-anchored research for TTL Indexes. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- TTL cleanup is asynchronous. The background task normally runs every 60 seconds, but load and deletion backlogs can extend retention beyond that interval. Therefore, applications requiring exact expiry should check expiration timestamps when reading or authorizing access. (high confidence) [source]
How-to and procedures
- Use BSON Date values or arrays containing dates. The earliest date in an array determines expiration. Missing fields and fields without date values do not expire documents; schema validation can prevent these silent retention gaps. (high confidence) [source]
- Use collMod to change an existing TTL index’s expireAfterSeconds without rebuilding the index; createIndex is not the mechanism for changing this setting. (high confidence) [source]
- Create a single-field TTL index with createIndex({createdAt: 1}, {expireAfterSeconds: 3600}) to expire documents one hour after their stored createdAt date. (high confidence) [source]
- Use collMod to change an existing TTL duration without rebuilding the index. Lowering retention or adding TTL to old data can create a delete backlog; pre-delete in batches and schedule the change during quiet periods. (high confidence) [source]
Problems, failure modes and limitations
- TTL requires a single-field index; compound indexes do not implement TTL, and the _id index cannot carry the TTL option. (high confidence) [source]
- Since MongoDB 7.0, time-series partial TTL indexes use timeField keys and metaField filters for shorter retention on matching data. Bucket deletion waits until all contained measurements expire; longer partial retention cannot override a shorter collection-wide retention period. (low confidence) (verified as of 2026-10-14) [source]
- Application inference: enforce a strict session or token deadline when reading or authorizing access; TTL cleanup alone cannot guarantee timely rejection of expired records. (medium confidence) [source]
- For PBM logical restores of time series collections with collection-level expireAfterSeconds, Percona warns that TTL can remove buckets needed by oplog replay. Its current procedure disables the monitor on each data-bearing target and restores its original setting afterward; it explicitly excludes regular TTL indexes from this failure. (low confidence) (verified as of 2026-10-05) [source]
Comparisons and alternatives
- TTL indexes automatically delete whole documents after the indexed date plus expireAfterSeconds. They suit bounded-lifetime logs and sessions; expiration depends on the field value, rather than insertion time unless the application stores insertion time there. (high confidence) [source]
- Inspect db.currentOp() and serverStatus metrics.ttl.deletedDocuments and metrics.ttl.passes to observe TTL activity. These report cleanup activity rather than proving that no expired documents remain. (high confidence) [source]
Facts and statements
- For per-document deadlines, index a BSON Date field such as expireAt and set expireAfterSeconds to 0. The stored date determines eligibility, not an exact deletion appointment. (high confidence) [source]
- In replica sets, the TTL monitor deletes only on the primary. Secondaries replicate the resulting deletions; cleanup consumes normal write and replication resources. (high confidence) [source]
- Building a TTL index over old data or shortening retention can expose a large deletion backlog. Estimate eligible data, delete in controlled batches, and schedule the change during off-peak hours. (high confidence) [source]
- A TTL index with zero $indexStats accesses.ops is not necessarily unused: this counter excludes internal TTL deletion activity. Dropping it based on this counter alone can silently remove automatic retention. (high confidence) [source]
- The documented monitor is single-threaded. It advances from an index after deleting 50,000 documents, spending one second, or exhausting its expired documents; passes and sub-passes share cleanup opportunities across indexes. (high confidence) (verified as of 2026-09-16) [source]
- Never configure expireAfterSeconds as NaN. MongoDB 5.0.0–5.0.13 and 6.0.0–6.0.1 treated NaN as zero, risking immediate expiration; 5.0.14 and 6.0.2 onward ignore such malformed TTL indexes according to the documented compatibility history. (low confidence) (verified as of 2026-10-14) [source]
- SERVER-92779 reports that enough expired orphan or unowned documents can stall TTL deletion of owned documents during chunk migration. The issue lists 6.1.0-rc0, 7.0.0 and 8.0.0 as affected and remained unresolved in its May 14, 2026 update. (low confidence) (verified as of 2026-05-14) [source]
- SERVER-56274 documented much slower TTL deletion with descending indexes on MongoDB 4.4.0 and records resolution in October 2022. Treat this as a historical performance defect, not a universal rule that descending TTL indexes are unsupported. (low confidence) [source]
- TTL deletion leaves empty WiredTiger records available for reuse but does not normally return that space to the operating system; compact or replica-set resync can release it. (high confidence) [source]
- The manual dates conversion of an existing single-field index to TTL through collMod to MongoDB 5.1. Alibaba Cloud's ApsaraDB for MongoDB guide documents this capability from 6.0 for its product; distinguish that product baseline from the original MongoDB introduction. (medium confidence) [source]
- Alibaba Cloud's ApsaraDB for MongoDB guide recommends adding a random offset to spread synchronized TTL expirations and avoid CPU spikes from mass deletions; for retention periods of at least 24 hours, it recommends a 0-to-10-minute offset. (low confidence) [source]
- MongoDB's manual dates batched TTL deletions and the BATCHED_DELETE stage to 6.1. Alibaba Cloud's ApsaraDB for MongoDB guide lists 7.0+ as its product baseline and says the feature first appeared in development version 6.1. (medium confidence) [source]
- A 2015 performance thread initially blamed TTL, but its reporter later identified the tags index after further tests. It does not establish a general TTL throughput penalty. (low confidence) [source]
Children
- TTL monitor scheduling and deletion backlogs (frontier)
- Absolute expiration and BSON Date validation (frontier)
- Time-series bucket expiration (frontier)
- TTL observability and retention rollout (frontier)
Frontier under this node: Absolute expiration and BSON Date validation, TTL monitor scheduling and deletion backlogs, TTL observability and retention rollout, Time-series bucket expiration