使用 expireAfterSeconds 自动过期数据

Time series data is almost always finite in value — sensor readings from 5 years ago rarely inform today's decisions. Retaining stale data wastes storage, slows backups, and increases index sizes. MongoDB's expireAfterSeconds option lets you declare a retention period at collection creation time so the database handles cleanup automatically, without cron jobs or application-level delete routines.

Pass expireAfterSeconds as a top-level option alongside the timeseries object when calling db.createCollection(). The value is an integer representing the number of seconds to retain data. Documents whose timeField value is older than now − expireAfterSeconds become eligible for deletion by the TTL background thread.

MongoDB's TTL thread runs approximately every 60 seconds. For time series collections, it deletes entire bucket documents rather than individual measurements. A bucket is only deleted when all measurements it contains are older than the expiry threshold. This makes TTL deletion highly efficient — removing one bucket document deletes hundreds of measurements in a single operation.

You can modify the retention period of an existing time series collection at any time using the collMod command — no downtime required. Increasing the value keeps data longer; decreasing it causes previously non-expiring data to become eligible for deletion at the next TTL run. The change takes effect within roughly 60 seconds.

Regular MongoDB collections use a TTL index (a special single-field index on a date field with an expireAfterSeconds attribute) to expire individual documents. Time series collections use a different mechanism — they expire entire bucket documents rather than individual measurement documents. This means you cannot create a separate TTL index on a time series collection; expiration is managed solely through the collection-level expireAfterSeconds option.

Inspect the current retention policy by running db.getCollectionInfos() and examining the options.expireAfterSeconds field. You can also check db.sensorReadings.stats() which reports the TTL configuration in its output. This is useful during audits to confirm production collections are set to the correct retention period.

A common production pattern is tiered retention: raw high-frequency data is stored in one time series collection with a short TTL (e.g., 7 days), while an aggregation pipeline job runs nightly to compute hourly summaries and writes them to a second collection with a longer TTL (e.g., 2 years). This balances storage costs with the need to analyse historical trends.

The TTL background thread wakes up every 60 seconds, so expiration is not instantaneous — data may survive up to 60 seconds beyond its threshold. On Atlas clusters under heavy load, TTL deletions may be further delayed. For compliance requirements demanding exact deletion at a specific second, manual deletion scripts or scheduled Atlas Triggers provide more deterministic control than TTL.

If you need to immediately remove a block of measurements — for example, to purge a faulty sensor's data — use deleteMany() with a filter on the timeField and metaField. Time series collections support deletes by time range and metaField value since MongoDB 5.1. Complex measurement-field filters on deletes are supported from MongoDB 6.0 onward.

MongoDB exposes TTL deletion metrics in server status under the metrics.ttl section. The deletedDocuments counter tracks how many documents (bucket documents for time series) the TTL thread has deleted since the mongod process started. Monitoring this counter helps you confirm that TTL is actually running and deleting data as expected in production.

When planning retention, consider three factors: compliance requirements (some regulations mandate data retention for years), analytical needs (how far back do your queries look?), and storage budget (what does keeping N days of data cost?). Model the storage growth by estimating daily document volume × average document size, then set expireAfterSeconds to balance all three constraints.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: expireAfterSeconds is set at the collection level (not via an index) and controls when entire buckets are purged, collMod lets you update the retention period on a live collection without downtime, and tiered retention — short TTL for raw data, long TTL for pre-aggregated summaries — is the production best practice for cost-effective time series storage. Next up we cover authentication mechanisms in MongoDB.