Creating a Time Series Collection
Learners will create a time series collection, specifying the timeField, metaField, and granularity options.
Creating a Time Series Collection is a free MongoDB Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Introduction to Time Series Collections
MongoDB 5.0 introduced native time series collections — a specialised collection type optimised for storing and querying measurements that change over time. Common use cases include IoT sensor readings, application metrics, financial ticks, and server monitoring data. Unlike regular collections, time series collections use a columnar storage format internally, dramatically reducing storage space and improving query performance on time-range filters.
Key Fields: timeField, metaField, granularity
Every time series collection requires three key options when created. The timeField is the document field that holds the timestamp (must be a BSON Date). The metaField identifies the series — for example, a sensor ID or device name. The granularity hint ('seconds', 'minutes', or 'hours') tells MongoDB how frequently measurements arrive, allowing it to optimise bucket sizing internally.
Creating With createCollection Command
Use db.createCollection() with a timeseries option object to create a time series collection. You cannot convert an existing regular collection to time series — you must create it fresh. The collection will appear in show collections with a special timeseries type indicator.
db.createCollection('sensorReadings', {
timeseries: {
timeField: 'timestamp',
metaField: 'sensorId',
granularity: 'seconds'
}
})Granularity Affects Bucket Sizing
The granularity option controls how MongoDB groups measurements into internal bucket documents. With 'seconds', buckets span one hour (3,600 measurements per bucket). With 'minutes', buckets span 24 hours. With 'hours', buckets span 30 days. Choosing the wrong granularity means more bucket documents and worse compression — always match granularity to your actual data arrival rate.
// Sensor sends data every second — use 'seconds'
db.createCollection('iotData', {
timeseries: {
timeField: 'ts',
metaField: 'device',
granularity: 'seconds'
}
})
// Aggregated hourly metric — use 'hours'
db.createCollection('hourlyMetrics', {
timeseries: {
timeField: 'ts',
metaField: 'service',
granularity: 'hours'
}
})Document Shape for Time Series Inserts
Documents inserted into a time series collection must include the timeField as a proper BSON Date. The metaField value identifies which series this measurement belongs to (e.g., a device ID). All other fields are called measurement fields and can hold any BSON value. MongoDB will reject documents where the timeField is missing or not a Date.
// Valid time series document
{
timestamp: new Date(), // timeField — must be a Date
sensorId: 'sensor-42', // metaField — identifies the series
temperature: 23.7, // measurement field
humidity: 55.2, // measurement field
pressure: 1013.4 // measurement field
}Inserting Single and Multiple Measurements
Insert into a time series collection exactly as you would a regular collection — using insertOne() or insertMany(). MongoDB handles the internal bucketing automatically. It is best practice to batch inserts with insertMany() when loading historical data, as this amortises the overhead of bucket creation across many measurements.
// Insert a single measurement
db.sensorReadings.insertOne({
timestamp: new Date('2024-06-01T10:00:00Z'),
sensorId: 'sensor-42',
temperature: 22.5,
humidity: 60.1
})
// Bulk insert historical data
db.sensorReadings.insertMany([
{ timestamp: new Date('2024-06-01T10:01:00Z'), sensorId: 'sensor-42', temperature: 22.6, humidity: 60.0 },
{ timestamp: new Date('2024-06-01T10:02:00Z'), sensorId: 'sensor-42', temperature: 22.4, humidity: 60.3 }
])Adding Automatic Expiration With expireAfterSeconds
Time series collections support automatic data expiration via the expireAfterSeconds option. Once set, MongoDB's background TTL thread deletes entire buckets when all measurements in the bucket are older than the threshold. This is more efficient than a regular TTL index because entire internal bucket documents are dropped at once rather than individual measurement documents.
// Create with 90-day TTL
db.createCollection('sensorReadings', {
timeseries: {
timeField: 'timestamp',
metaField: 'sensorId',
granularity: 'minutes'
},
expireAfterSeconds: 60 * 60 * 24 * 90 // 90 days
})Querying Time Series Collections
Queries on time series collections look identical to regular find() queries. MongoDB automatically uses the internal bucket structure to skip irrelevant buckets when filtering by time range. Filtering on the metaField is also highly efficient. Avoid querying only on measurement fields without a time or meta filter, as this forces a full collection scan across all buckets.
// Query last 24 hours for a specific sensor
const since = new Date(Date.now() - 24 * 60 * 60 * 1000)
db.sensorReadings.find({
sensorId: 'sensor-42',
timestamp: { $gte: since }
}).sort({ timestamp: 1 })Updating the Granularity After Creation
You can increase the granularity of an existing time series collection (e.g., from 'seconds' to 'minutes') using the collMod command. However, you cannot decrease it — MongoDB will return an error if you try to move from 'minutes' back to 'seconds'. Updating the expireAfterSeconds setting is also possible via collMod without recreating the collection.
// Increase granularity from seconds to minutes
db.runCommand({
collMod: 'sensorReadings',
timeseries: { granularity: 'minutes' }
})
// Update expireAfterSeconds to 30 days
db.runCommand({
collMod: 'sensorReadings',
expireAfterSeconds: 60 * 60 * 24 * 30
})Limitations and Restrictions
Time series collections have a few important restrictions compared to regular collections. You cannot shard a time series collection on the timeField alone — a hashed metaField component is required. Updates and deletes are limited: before MongoDB 5.1, only deletes by metaField or time range were supported. Additionally, time series collections do not support unique indexes, sparse indexes, or capped collections.
Verifying Collection Type and Options
After creating a time series collection, inspect it using db.getCollectionInfos() to confirm the timeseries options are correctly stored. You can also run db.sensorReadings.stats() to see storage statistics, including the number of internal bucket documents MongoDB is maintaining behind the scenes.
// Inspect time series collection metadata
db.getCollectionInfos({ name: 'sensorReadings' })
// Check storage stats
db.sensorReadings.stats()Quick Check
Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.
Lesson Recap
In this lesson you learned: time series collections use a columnar bucket format for high-compression append-heavy workloads, three key options (timeField, metaField, granularity) control how measurements are organised and bucketed, and expireAfterSeconds enables efficient automatic purging of old data at the bucket level. Next up we explore inserting and querying time series data in depth.
Frequently asked questions
Is the “Creating a Time Series Collection” lesson free?
Yes — the full text of “Creating a Time Series Collection” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.
What will I learn in “Creating a Time Series Collection”?
Learners will create a time series collection, specifying the timeField, metaField, and granularity options. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MongoDB Academy?
No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Creating a Time Series Collection” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MongoDB Academy lesson?
Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Creating a Time Series Collection
- Inserting and Querying Time Series Data
- Windowed Aggregations on Time Series
- Automatic Data Expiration With expireAfterSeconds