Inserting and Querying Time Series Data
Learners will insert batches of measurements and query them with filters on time ranges and metadata fields.
Inserting and Querying Time Series Data is a free MongoDB Academy lesson on CoddyKit — lesson 2 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.
Inserting Measurements Into Time Series
Inserting into a time series collection uses the exact same insertOne() and insertMany() methods as regular collections. MongoDB inspects the timeField (which must be a BSON Date) and the metaField to place the measurement into the correct internal bucket. The insert API is intentionally identical so existing application code requires minimal changes when adopting time series collections.
const now = new Date()
db.sensorReadings.insertOne({
timestamp: now,
sensorId: 'sensor-42',
temperature: 23.1,
humidity: 58.4,
batteryLevel: 87
})Bulk Inserting Historical Data
When loading historical measurements, always prefer insertMany() over repeated insertOne() calls. MongoDB can batch the data into buckets far more efficiently with bulk operations. For very large datasets (millions of rows), consider using mongoimport or the Node.js driver's bulkWrite() with insertOne operations grouped in batches of 1,000–5,000 documents.
const readings = []
const base = new Date('2024-06-01T00:00:00Z')
for (let i = 0; i < 1440; i++) {
readings.push({
timestamp: new Date(base.getTime() + i * 60000),
sensorId: 'sensor-42',
temperature: 20 + Math.random() * 5,
humidity: 50 + Math.random() * 20
})
}
db.sensorReadings.insertMany(readings)Basic Time-Range Queries
The most common query pattern for time series data is a time-range filter on the timeField using $gte and $lte. MongoDB uses the internal bucket boundaries to skip entire buckets that fall outside the requested range, achieving much better performance than scanning every document. Always include a time filter when querying large time series collections.
// Last 1 hour of readings from one sensor
const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000)
db.sensorReadings.find({
sensorId: 'sensor-42',
timestamp: { $gte: oneHourAgo }
}).sort({ timestamp: 1 })
// Specific day range
db.sensorReadings.find({
timestamp: {
$gte: new Date('2024-06-01T00:00:00Z'),
$lt: new Date('2024-06-02T00:00:00Z')
}
})Filtering on Metadata Fields
Filtering on the metaField is highly optimised — MongoDB stores the meta value at the bucket level and can skip entire buckets belonging to other series without inspecting individual measurements. This makes queries like 'all readings from sensor-42 in the last 6 hours' extremely fast even on collections holding billions of measurements from thousands of sensors.
// Query a specific device
db.sensorReadings.find({
sensorId: 'sensor-42',
timestamp: { $gte: new Date('2024-06-01T00:00:00Z') }
})
// Query multiple devices using $in on the metaField
db.sensorReadings.find({
sensorId: { $in: ['sensor-42', 'sensor-43', 'sensor-44'] },
timestamp: { $gte: new Date('2024-06-01T00:00:00Z') }
})Aggregating Time Series With $match and $group
The aggregation pipeline is the primary tool for computing statistics over time series data. A typical pattern is to $match on the time range and metaField first (so MongoDB can skip irrelevant buckets), then $group to compute averages, minimums, and maximums. Always place $match as the very first stage to enable bucket pruning.
// Average temperature per hour for one sensor
db.sensorReadings.aggregate([
{
$match: {
sensorId: 'sensor-42',
timestamp: { $gte: new Date('2024-06-01T00:00:00Z') }
}
},
{
$group: {
_id: {
year: { $year: '$timestamp' },
month: { $month: '$timestamp' },
day: { $dayOfMonth: '$timestamp' },
hour: { $hour: '$timestamp' }
},
avgTemp: { $avg: '$temperature' },
maxTemp: { $max: '$temperature' },
minTemp: { $min: '$temperature' }
}
},
{ $sort: { '_id.hour': 1 } }
])Using $dateTrunc for Time Bucketing
The $dateTrunc aggregation expression (added in MongoDB 5.0) simplifies grouping measurements into fixed-width time windows. It truncates a date to the nearest unit boundary — for example, truncating to 'hour' groups all measurements within the same hour under the same key. This replaces the verbose multi-field date extraction approach.
// Group readings into 15-minute windows
db.sensorReadings.aggregate([
{
$match: {
sensorId: 'sensor-42',
timestamp: { $gte: new Date('2024-06-01T00:00:00Z') }
}
},
{
$group: {
_id: {
$dateTrunc: {
date: '$timestamp',
unit: 'minute',
binSize: 15
}
},
avgTemp: { $avg: '$temperature' },
count: { $sum: 1 }
}
},
{ $sort: { _id: 1 } }
])Projecting Time Series Results
Use projection to limit the fields returned from time series queries, just as with regular collections. Projecting only the fields you need reduces network transfer and client memory usage. Note that the timeField and metaField are always available for projection, and the _id field can be suppressed with _id: 0.
// Return only timestamp and temperature
db.sensorReadings.find(
{
sensorId: 'sensor-42',
timestamp: { $gte: new Date('2024-06-01T08:00:00Z') }
},
{
_id: 0,
timestamp: 1,
temperature: 1
}
).sort({ timestamp: 1 })Counting and Sampling Measurements
Use countDocuments() with a filter to count measurements in a time range. For large collections, estimatedDocumentCount() provides a fast approximate total using collection metadata. When debugging or building dashboards, $sample in an aggregation pipeline lets you retrieve a random subset of measurements without scanning the full result set.
// Count readings in last 24 hours
const since = new Date(Date.now() - 86400000)
db.sensorReadings.countDocuments({
sensorId: 'sensor-42',
timestamp: { $gte: since }
})
// Random sample of 10 recent measurements
db.sensorReadings.aggregate([
{ $match: { timestamp: { $gte: since } } },
{ $sample: { size: 10 } }
])Node.js Driver: Reading Time Series Data
In a Node.js application, querying time series collections is identical to querying regular collections. Use the standard find() or aggregate() methods on the collection object. Since time series queries often return large result sets, use async iteration over the cursor rather than loading everything into memory with toArray().
const { MongoClient } = require('mongodb')
async function getRecentReadings(client) {
const db = client.db('iot')
const col = db.collection('sensorReadings')
const since = new Date(Date.now() - 3600000) // last hour
const cursor = col.find(
{ sensorId: 'sensor-42', timestamp: { $gte: since } },
{ projection: { _id: 0, timestamp: 1, temperature: 1 } }
).sort({ timestamp: 1 })
for await (const doc of cursor) {
console.log(doc.timestamp, doc.temperature)
}
}Performance: Why Time Range First
The golden rule of querying time series data is: always filter by time range before anything else. MongoDB's bucket pruning only activates when the timeField filter appears in the query. Without it, MongoDB must scan every bucket. Additionally, combine the time filter with the metaField filter to leverage both forms of bucket skipping — time boundaries and series identity.
// GOOD: time + meta filter — fast bucket pruning
db.sensorReadings.find({
sensorId: 'sensor-42', // prune by series
timestamp: { $gte: since }, // prune by time
temperature: { $gt: 30 } // measurement filter applied after pruning
})
// BAD: no time filter — scans all buckets
db.sensorReadings.find({
temperature: { $gt: 30 } // forces full scan
})Monitoring Bucket Utilisation
You can inspect the internal bucket documents using a system namespace: system.buckets.<collectionName>. While you cannot write to this namespace directly, reading it reveals how many buckets exist and how many measurements each bucket holds. This is useful when tuning granularity — ideally each bucket should be close to its maximum fill level (3,600 for 'seconds' granularity).
// Count internal bucket documents
db['system.buckets.sensorReadings'].countDocuments()
// Inspect a sample bucket (internal format)
db['system.buckets.sensorReadings'].findOne()Quick Check
Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.
Lesson Recap
In this lesson you learned: insertMany() with batches is the efficient way to load time series data, filtering by timeField and metaField together enables bucket pruning for fast range queries, and $dateTrunc in aggregation pipelines simplifies grouping measurements into fixed-width time windows. Next up we explore windowed aggregations over time series using $setWindowFields.
Frequently asked questions
Is the “Inserting and Querying Time Series Data” lesson free?
Yes — the full text of “Inserting and Querying Time Series Data” 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 “Inserting and Querying Time Series Data”?
Learners will insert batches of measurements and query them with filters on time ranges and metadata fields. 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 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Inserting and Querying Time Series Data” 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