Inserire e interrogare dati 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.

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.

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.

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.

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.

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.

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.

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.

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().

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.

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).

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.