How does a MongoDB TTL index with expireAfterSeconds actually delete expired documents?

## The mechanism A TTL index is an ordinary single-field index plus one option: ```javascript db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 3600 }) ``` Nothing about the *storage* of the document changes. What changes is that a background thread in `mongod` — the TTL monitor — now has a job to do. It wakes on a fixed cycle, by default about every 60 seconds, walks the TTL index looking for entries whose indexed date plus `expireAfterSeconds` lies in the past, and deletes those documents. The deletes are completely ordinary: they take the same locks, produce the same oplog entries, and fire the same change-stream events as a delete your application issued. That single fact explains almost every TTL question an interviewer will ask. ## Expiry is approximate Between the moment a document becomes eligible and the moment it disappears there is at minimum the remainder of the current monitor cycle, plus however long the deletion pass takes. Under load, or when a large backlog has accumulated (say you shortened the TTL, or the server was down for a day), the lag can be much larger than a minute. The engineering consequence is that **you cannot treat the collection as if expired documents are gone**. If a session must stop being valid at exactly the one-hour mark, the read path still has to check the timestamp; the TTL index is a space-reclamation mechanism, not an access-control mechanism. Candidates who answer "the document is removed the instant it expires" are usually the ones whose sessions stay usable for an extra minute in production. ## The deletes cost real write throughput Because they are normal deletes, TTL removals consume the same resources as application writes: index maintenance for every index on the collection, oplog space, replication bandwidth, and cache churn. Expiring millions of documents at once is a genuine load event. Two practical rules follow. First, be careful about *shortening* a TTL on a large collection — you have just queued a very large delete storm. Second, watch for a workload where the TTL monitor never catches up because the insert rate exceeds the delete rate; the collection grows without bound even though the index is configured correctly. A related surprise: freed space returns to the storage engine but does not necessarily shrink files on disk, so a TTL collection can hold steady in document count while occupying much more disk than the live data suggests. ## What actually expires Rules that get asked directly: - The index must be **single-field**. A compound index cannot carry `expireAfterSeconds`. - The indexed field must hold a **BSON date**. A string like `"2026-01-01"`, a number, or a missing field means the document is never expired. This is the single most common bug: the app stored an ISO string and the collection never shrinks. - If the field holds an **array of dates**, the earliest date in the array determines expiry. - TTL indexes are not supported on capped collections, since MongoDB cannot remove arbitrary documents from one. - The `_id` index cannot be made a TTL index. ## The expireAfterSeconds: 0 pattern Setting `expireAfterSeconds: 0` means "expire at the time stored in the field" rather than "expire immediately". You write an explicit `expiresAt` date into each document and the monitor removes it once the clock passes that value. This is how you get per-document lifetimes — a two-hour password-reset token and a thirty-day export in the same collection — instead of one collection-wide duration. ```javascript db.tokens.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }) db.tokens.insertOne({ userId: 7, expiresAt: new Date(Date.now() + 2 * 3600 * 1000) }) ``` ## Replica sets Only the primary runs TTL deletions. Secondaries keep the TTL index but do not act on it independently; they receive the deletes through the oplog like any other write. This preserves the ordering guarantee that makes replication work — if each member expired documents on its own clock, members would diverge. It also means that during a period where a member lags, expired documents remain readable on that secondary until it catches up, which matters if you serve reads from secondaries. ## Changing and monitoring You can change the duration in place without rebuilding the index: ```javascript db.runCommand({ collMod: "sessions", index: { keyPattern: { createdAt: 1 }, expireAfterSeconds: 86400 } }) ``` Server status exposes counters for how many documents the TTL monitor has deleted and how many passes it has made; those are the metrics to alert on when you suspect the monitor is falling behind. And because a TTL index is a real index, it still serves ordinary range queries on that date field — you do not need a second index for "documents created in the last hour".