MongoDB · Data Modeling

MongoDB Time Series Collections: your metrics don't belong in a regular collection

Metrics ticking in once a second, sensor readings, market ticks — if you're still storing them one document per data point in a regular collection, you're already paying for storage and query costs you don't need to. MongoDB 5.0 introduced Time Series Collections specifically for this kind of data.

01 · The Problem

One document per data point costs more than it looks like

Time series data shares a common shape: massive volume, highly repetitive structure, and rarely ever updated individually. Store it in a regular collection and every single measurement becomes its own document — field names repeated over and over, index entries growing one-to-one with data points, BSON overhead stacking up with every row. As volume climbs, storage cost grows faster than the data itself.

Field names get stored again in every single document, so compression is poor
A time-range query has to scan through a huge number of scattered, tiny documents
Index entries scale one-to-one with raw data points — the index itself balloons too
02 · How Buckets Work

Packing a lot of points into one bucket

When a time series collection receives writes, it automatically groups multiple measurements that share the same time window and the same metadata into a single internal bucket document — holding up to roughly 1,000 data points, stored with columnar compression that dramatically cuts storage size. At query time, MongoDB automatically "unpacks" the bucket so you still see the familiar, per-document structure you'd expect — the whole mechanism is completely transparent to the user.

Raw Measurements
One per second, each its own point
Auto-Bucketed
Bucket Document
≈1,000 points / bucket · columnar compressed
At Query Time
{
  time: ...,
  tag: "cpu",
  value: 42.3
}
Still Looks Like a Normal Document
The query interface is fully transparent
timeField

The required timestamp field — it places each point on the timeline and is the core basis for how bucketing happens.

metaField

The field used for grouping — a device ID, hostname, or metric name. Points sharing the same meta are more likely to land in the same bucket.

granularity

seconds / minutes / hours — sets how much time span a single bucket covers, and should match your actual write frequency.

03 · Getting Started

Creating one is this simple

Creating a time series collection just means passing an extra timeseries option to createCollection. Reading and writing after that looks almost identical to a regular collection.

// 1. Create the time series collection
db.createCollection("metrics", {
  timeseries: {
    timeField: "timestamp",
    metaField: "metadata",
    granularity: "seconds"
  }
})
// 2. Writes look exactly like a regular collection
db.metrics.insertOne({
  timestamp: ISODate("2026-09-10T08:00:00Z"),
  metadata: { host: "db-node-02", metric: "cpu" },
  value: 42.3
})
// 3. Queries look exactly like a regular collection too
db.metrics.find({ "metadata.host": "db-node-02" })
  .sort({ timestamp: -1 })
04 · When to Use It

The typical fit: high-frequency, append-only data

Time series collections aren't a universal fix, but whenever data fits the shape of "high-frequency writes, organized by timestamp, almost never randomly updated," they're very likely the better answer.

IoT Sensor Readings

Thousands of devices reporting temperature, humidity, location, and more every second.

App & Infrastructure Metrics

CPU, memory, latency, QPS — the kind of operational metrics collected second by second.

Financial Tick Data

High-frequency quote and trade records, demanding both high write throughput and fast range queries.

Logs & Event Tracking

User behavior or system events generated in chronological order and almost never revised afterward.

WAP Note

This is exactly why WAP itself stores its own cluster monitoring metrics in a time series collection — the millions of metric points generated every day would cost several times more to store without bucket-based compression.

05 · A Few Easy Mistakes

Check these before you commit

Granularity doesn't match the actual write frequencyPick seconds / minutes / hours to match your ingest interval
Frequently-updated, mutable data gets shoved in tooTime series collections fit "append-only, rarely modified" data best
No attention paid to time series feature support across versionsConfirm the target version's index and query capabilities before upgrading
One Last Thing

Picking the right storage model is one of
the highest-leverage architecture decisions

Time series collections solve a data-modeling problem. Whether the cluster underneath stays stable — and whether anyone has to get out of bed at 3 a.m. for it — is a separate job. That one belongs to Whaleal Platform.