mongodb-time-series

Parent: mongodb-schema-design · Published reference · snapshot 2026-09-08 · skill mongodb-expert/references/mongodb-time-series.md

↓ Facts as markdown all context files

MongoDB Time Series Collections, introduced in MongoDB 5.0 (GA), are a specialized collection type optimized for time-stamped measurement data. They use an internal columnar storage format with automa

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Overview

MongoDB Time Series Collections, introduced in MongoDB 5.0 (GA), are a specialized collection type optimized for time-stamped measurement data. They use an internal columnar storage format with automatic bucketing, delta encoding, and Zstd compression to achieve 50-90% storage reduction over regular collections while dramatically improving query performance for time-range access patterns. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
Time series collections are the preferred choice over the manual bucket pattern for IoT sensor data, server metrics, financial tick data, application events, observability signals, and any domain where data is appended in timestamp order and queried by time range. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
> Skill boundaries: > - Use this skill (mongodb-time-series) for: collection creation options, bucket internals, TTL, time-series-specific index constraints, $densify/$fill/$dateTrunc/$setWindowFields in a time-series context, Atlas triggers/change-stream limitations, migration, sharding for time series, and performance sizing. > - Use mongodb-aggregation-pipeline for: general pipeline stage design, $lookup, $merge/$out to regular collections, explain profiling, memory/allowDiskUse tuning. > - Use mongodb-schema-design for: the manual bucket pattern, embedding vs referencing decisions, general IoT schema modeling without the native time series collection type. > - Use mongodb-indexes-deep for: ESR compound index design, partial/sparse/wildcard/text index types on regular collections. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
Version timeline: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 5.0: Initial release (create, insert, query, TTL, basic indexing) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 5.1: $densify aggregation stage [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 5.2: Columnar compression format (major storage improvement) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 5.3: $fill aggregation stage [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 6.0: partial index support with $or/$in/$geoWithin [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 6.3: Custom bucketing parameters (bucketMaxSpanSeconds, bucketRoundingSeconds) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 7.0: $out can write to time series collections; TTL partial filter on metaField [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 8.0: Block processing - direct write into column-compressed format (2-3x throughput, 10-20x cache reduction); timeField shard key deprecated [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 8.3: timeField cannot start with $; creating "_id_" index returns error [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- Atlas (2023+): Atlas Stream Processing introduced - time series collections can be a sink but not a $source (no change stream support) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB Time Series Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- MongoDB 8.0 Block Processing Blog [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]
- Columnar Storage Cost Savings Blog [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#overview]

1. Collection Creation and Configuration

Time series collections are created with db.createCollection() using a timeseries subdocument. The timeField is the only required parameter; all others are optional but significantly affect performance. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
Parameter reference: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
Granularity and bucket time spans: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
Changing parameters after creation: Use collMod to update granularity, bucketMaxSpanSeconds, bucketRoundingSeconds, and expireAfterSeconds. You can only increase bucket span, never decrease it. timeField and metaField are permanently immutable. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
- Time Series Considerations [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
- Create and Query Procedures v7.0 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]
- Community: Granularity and metaField [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#1-collection-creation-and-configuration]

2. Internal Bucket Architecture

MongoDB stores time series documents in internal system.buckets.<collectionName> bucket documents, not as individual BSON records. The view layer (<collectionName>) presents unpacked measurements to applications. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
Bucket structure: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
Bucket lifecycle: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- A bucket is opened when the first measurement for a given metaField value arrives. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- A bucket is closed when it reaches either ~1,000 measurements OR ~125 KB, whichever comes first, or when the bucket's time span limit (determined by granularity) is exceeded. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Closed buckets are compressed and eligible for WiredTiger cache eviction. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
Compression mechanisms (MongoDB 5.2+): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Column-oriented storage: Values for each field (temperature, humidity, pressure) are stored together rather than per-document. This enables delta encoding and RLE to be applied across entire columns. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Delta encoding: Stores the first value absolutely, then subsequent values as differences (+0.1, -0.2). Highly effective for monotonic timestamps and slowly changing sensor readings. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Run-Length Encoding (RLE): Repeated values (e.g., status: "active" for 1,000 measurements) stored as (value, count). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Metadata deduplication: Field names and BSON types stored once per bucket rather than per document. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Zstd block compression (WiredTiger level): Applied on top of the already column-compressed data. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
MongoDB 8.0 block processing: Documents are written directly into column-compressed format, eliminating the decompression-recompression cycle on write. This results in 2-3x write throughput improvement and 10-20x cache usage reduction compared to MongoDB 7.0 for time series workloads. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Columnar Storage Blog [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- Time Series Compression [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- High vs Low Ingestion Study [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]
- MongoDB 8.0 Block Processing [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#2-internal-bucket-architecture]

3. Secondary Indexes

Time series collections index at the bucket level, not the document level. The control.min and control.max values on each bucket function as a clustered range index that enables bucket-level pruning for time-range queries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
Default clustered index: A clustered index on the metaField and timeField is automatically created. No explicit _id index is created (unlike regular collections). In MongoDB 5.0, only a single compound index on metaField + timeField was supported; secondary indexes on measurement fields were added in later versions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
> Skill boundary: For general compound index design (ESR rule, multikey, partial, sparse, wildcard), use mongodb-indexes-deep. This section covers only time-series-specific index constraints and patterns. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
Supported secondary index types: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
Adding a compound secondary index: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
Key indexing constraints: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- partialFilterExpression can only reference the metaField (not measurement fields). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- Unique indexes are not supported - duplicate prevention must be handled at the application layer or using $match + $group in aggregation. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- Text indexes are not supported - consider Atlas Search for full-text needs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- The distinct() command is not efficiently supported; use $group with a supporting compound index instead. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
Query on object metaField - use sub-field dot notation: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- Time Series Indexes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- Add Secondary Indexes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]
- Time Series Limitations [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#3-secondary-indexes]

4. TTL and Automatic Data Expiration

Time series collections support bucket-granularity TTL via expireAfterSeconds. Unlike regular collection TTL indexes (which delete individual documents), TTL on time series collections deletes entire buckets once all measurements within the bucket are older than the threshold. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
Modify after creation (cannot use createIndex): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- The background TTL task runs every 60 seconds. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- A bucket is deleted only when all measurements in that bucket have expired (i.e., control.max.timestamp + expireAfterSeconds < now). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- Because of bucket aggregation, actual deletion may be delayed by up to bucket-span + 60s after expiration. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- A bucket created with granularity: "hours" covering a 30-day span won't be deleted until all 30 days of measurements within it have expired. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
Tiered TTL pattern (MongoDB 7.0+ with partial filter): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- TTL for Time Series [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]
- TTL Indexes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#4-ttl-and-automatic-data-expiration]

5. Aggregation Pipeline — Time Series Optimizations

MongoDB provides three specialized aggregation stages that are particularly valuable for time series analysis: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
> Skill boundary - aggregation stages: For general aggregation pipeline design ($lookup, $group, $merge, $out, explain profiling, memory limits), use mongodb-aggregation-pipeline. This section covers only time-series-optimized stages ($densify, $fill) and time-series-specific $setWindowFields usage. $dateTrunc (for downsampling into time buckets) is also covered here as it is the primary time-bucketing operator. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
#### $dateTrunc - Time-Bucket Downsampling [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
$dateTrunc truncates a date to a specified granularity boundary. It is the canonical operator for downsampling raw measurements into fixed time buckets (minute candles, hourly rollups, daily aggregates). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
The binSize parameter (MongoDB 5.0+) groups dates into multiples of the unit - e.g., binSize: 5, unit: "minute" snaps all timestamps to 5-minute boundaries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
#### $densify (MongoDB 5.1+) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
Fills gaps in a time series by inserting synthetic documents at regular intervals where data is missing. Critical for dashboards and window function inputs that assume uniform spacing. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- "full" - spans min to max across all documents in the collection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- "partition" - spans min to max within each partition group. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- [lower, upper] - explicit range; lower inclusive, upper exclusive. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
#### $fill (MongoDB 5.3+) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
Populates null or missing fields in densified documents using interpolation or last-observed-carry-forward (LOCF). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- "linear" - calculates value proportionally between surrounding non-null values. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- "locf" (Last Observation Carried Forward) - repeats the last known non-null value. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
#### $setWindowFields (MongoDB 5.0+) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
Applies window functions over ordered partitions without collapsing documents (unlike $group). Enables rolling averages, cumulative sums, lag/lead comparisons, and rankings - all SQL-standard window function patterns. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- documents: ["unbounded", "current"], [-N, M] - count-based. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- range: [-N, M] with unit for time-based (ms, second, minute, hour, day, week, month, quarter, year). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
Important performance note: Window functions on time series collections do not automatically push down through the bucket storage format. Use $match on metaField and timeField before $setWindowFields to minimize the scanned document set. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- $densify Reference [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- $setWindowFields Reference [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- Percona Window Functions in MongoDB 5.0 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]
- MongoDB Developer: time-series-window-functions [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#5-aggregation-pipeline-time-series-optimizations]

6. Atlas-Specific Features

#### Atlas Charts Integration [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Atlas Charts works natively with time series collections. The time-series-optimized aggregation engine (bucket-level pruning, columnar projection) applies to Charts queries automatically - no special configuration needed. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Use cases with Atlas Charts: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Real-time IoT sensor dashboards using time-range filters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Environmental monitoring with rolling average overlays [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Infrastructure metrics with aggregated panels (mean, p95, max) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Financial dashboards showing OHLCV candlestick data [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Limitation: Embedded charts querying time series collections with a high-cardinality metaField can generate expensive scatter-gather queries. Use time-range and metaField equality filters in the embedded chart filter to scope queries. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Visualizing Atlas Data with Charts [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- IoT + Atlas Charts Example [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
#### Atlas Triggers - Not Supported [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Time series collections do not support change streams and therefore cannot use Database Triggers. The optimized bucket storage format does not emit per-document change events. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Workaround patterns: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Dual-write to a regular collection: Write events to both a regular collection (for triggers) and a time series collection (for historical queries). The regular collection can be capped or have a short TTL. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Scheduled triggers: Use scheduled Atlas triggers to run aggregations over the time series collection at regular intervals and emit derived events or aggregated results to another collection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Atlas Stream Processing: Use Kafka or Atlas Stream Processing $source stage to consume events before they enter the time series collection and react in real-time. Note: time series collections cannot serve as a $source in ASP. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Community: Change Stream Workaround [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Triggers Limitations [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
#### Atlas Flex Clusters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
Atlas Flex clusters (the replacement for M2/M5 and Serverless instances, as of January 2026) support time series collections as they run MongoDB 5.0+ wire protocol. However, Flex clusters have limitations compared to Dedicated clusters: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- No Continuous backup / Point-in-Time Restore (snapshots only) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- No cross-region replication [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Private Endpoints support is limited - verify current availability in the Atlas docs, as Flex private endpoint support has been expanding since 2025 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
For production time series workloads requiring PITR, guaranteed HA, or private networking, use Dedicated clusters (M10+). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Manage Flex Clusters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]
- Flex Migration Guide [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#6-atlas-specific-features]

7. Sharding Time Series Collections

Sharding enables horizontal scaling for very high ingestion rates. Time series sharding has several important constraints that differ from regular collection sharding. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- Shard key must contain only the metaField, sub-fields of metaField, or (deprecated) the timeField. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- timeField as a shard key component is deprecated in MongoDB 8.0 because monotonically increasing values cause write hotspots on a single shard. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- metaField can be used as a ranged or hashed shard key. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- Zone sharding is not supported for time series collections. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
Recommended shard key patterns: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
Anti-pattern - timeField-only shard key: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
Pre-splitting: If device groups or regions are known in advance, pre-split chunks before ingestion to avoid initial primary-shard hotspot. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- Shard a Time Series Collection [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]
- Time Series Limitations - Sharding [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#7-sharding-time-series-collections]

8. Performance Benchmarks and Working Set Sizing

#### Storage Compression [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
#### Write Performance (MongoDB 8.0 vs 7.0) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
#### Working Set Sizing for Time Series [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
Unlike regular collections where the working set is the "hot" subset of documents, for time series the working set is primarily: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Open buckets (currently being written) - proportional to metaField cardinality. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Recently queried time ranges - based on your typical query lookback window. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
Granularity bucket span seconds reference: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- seconds granularity → 3,600 s (1 hour) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- minutes granularity → 86,400 s (24 hours) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- hours granularity → 2,592,000 s (30 days) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
Example (10,000 IoT sensors, minutes granularity = 86,400 s span, 1-hour lookback): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
(At seconds granularity the same 1-hour lookback covers exactly 1 bucket span, so recent-query RAM ≈ open-bucket RAM = ~1.2 GB - an important difference when choosing granularity.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
Recommendation: Size WiredTiger cache (storage.wiredTiger.engineConfig.cacheSizeGB) at 50-60% of available RAM, targeting > 95% cache hit rate. Monitor wiredTiger.cache.bytes currently in the cache and page faults in Atlas metrics. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Columnar Storage Cost Savings Blog [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Time Series Compression Docs [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Bucket Behavior Study [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]
- Medium: Storage Comparison [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#8-performance-benchmarks-and-working-set-sizing]

Pattern 1: IoT Multi-Sensor Ingestion

Batched insertion (critical for performance): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#pattern-1-iot-multi-sensor-ingestion]

Pattern 5: Versioning for Correctable Measurements

Time series collections cannot update measurement fields. Use the versioning pattern to handle corrections: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#pattern-5-versioning-for-correctable-measurements]
Source: Versioning Pattern with Time Series Data [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#pattern-5-versioning-for-correctable-measurements]

Migration: Regular Collection to Time Series

You cannot convert an existing collection in-place. Migration always requires creating a new time series collection and copying data. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#migration-regular-collection-to-time-series]

Method 3: Kafka Connector (streaming cutover)

For live production systems with continuous ingestion, use the MongoDB Kafka Connector to dual-write during cutover: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Configure source connector reading from existing collection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Configure sink connector writing to new time series collection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Once data is synced and validated, cut application writes over to the time series collection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Drain and stop connectors. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Migrate with Aggregation Pipeline [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Migrate with Database Tools [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]
- Kafka Connector Migration Tutorial [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#method-3-kafka-connector-streaming-cutover]

Anti-Pattern 2: Wrong Granularity for Ingestion Rate

Mismatch 1 - granularity too coarse (high-frequency data): Setting granularity: "hours" for a sensor that reports every second means each bucket can remain open for up to 30 days before the time limit triggers a close. In practice, the measurement-count limit (~1,000 documents) is hit first (after ~17 minutes at 1/s), but this still produces far more bucket churn than needed and misrepresents the intended data cadence to the storage engine, degrading compression locality. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#anti-pattern-2-wrong-granularity-for-ingestion-rate]
Mismatch 2 - granularity too fine (low-frequency data): Setting granularity: "seconds" for a sensor that only reports once per hour means each bucket closes after 1 hour (time limit), typically containing only ~1 measurement. This destroys compression - you lose all the benefit of columnar storage across many measurements. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#anti-pattern-2-wrong-granularity-for-ingestion-rate]

Anti-Pattern 3: High metaField Cardinality with Unbounded Values

Each unique metaField value maintains a separate open bucket in the working set. If metaField includes a UUID or a user-specific ID that changes per request, the working set explodes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#anti-pattern-3-high-metafield-cardinality-with-unbounded-values]

Issue: Buckets are Too Large / Too Small

Fix: Adjust granularity or bucketMaxSpanSeconds with collMod. Remember: you can only increase span, not decrease it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-buckets-are-too-large-too-small]

Issue: Queries Are Slow Despite Indexes

Look for COLLSCAN on system.buckets.* - this indicates missing indexes or the query optimizer not using bucket-level pruning. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-queries-are-slow-despite-indexes]
- Querying measurement fields in $match without preceding metaField filter. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-queries-are-slow-despite-indexes]
- Not using dot notation on metaField sub-fields. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-queries-are-slow-despite-indexes]
- Missing compound index for the combination of metaField sub-field + timeField. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-queries-are-slow-despite-indexes]

Issue: High Memory / WiredTiger Cache Pressure

Symptoms: High cache utilization, frequent evictions, rising page faults. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]
Diagnosis: High metaField cardinality generating too many open buckets. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]
- Reduce metaField cardinality by grouping sensors into logical partitions. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]
- Increase granularity to close buckets faster (shorter time span per bucket). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]
- Upgrade to MongoDB 8.0 for 10-20x cache reduction from block processing. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]
- Scale up cluster tier (more RAM) or scale out (sharding). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-high-memory-wiredtiger-cache-pressure]

Issue: TTL Not Deleting Data

Verify expiration config: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-ttl-not-deleting-data]
- expireAfterSeconds was never set at creation (default: no expiration). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-ttl-not-deleting-data]
- Bucket span is too large - the bucket won't delete until ALL measurements in it expire. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-ttl-not-deleting-data]
- Background TTL task has lag (up to 60s + bucket span after last measurement expires). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#issue-ttl-not-deleting-data]

References

MongoDB Time Series Collections - Official Documentation - Core reference for all time series features. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Time Series Limitations - Comprehensive list of unsupported operations. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Best Practices for Time Series Collections - Official best practices: compression, batching, metaField design. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Columnar Storage Cost Savings - MongoDB Engineering Blog - Delta encoding, RLE, and Zstd compression mechanics with benchmarks. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
MongoDB 8.0 Block Processing - 2-3x throughput and 10-20x cache reduction from direct columnar writes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
High vs Low Ingestion Bucket Behavior Study - Empirical study of granularity impact on bucket lifecycle under different ingestion rates. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
$densify Reference - Full parameter reference and examples. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
$setWindowFields Reference - Window function accumulator and range options. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Migrate Data into a Time Series Collection - Official migration procedures. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Versioning Pattern with Time Series Data - Pattern for handling measurement corrections. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Window Functions and Time Series Performance - Medium - Performance analysis of $setWindowFields with time series collections. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]
Shard a Time Series Collection - Sharding rules and shard key selection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-time-series/#references]

Where this helps

IoT sensor fleets reporting periodic measurements (temperature, humidity, GPS) where you need efficient storage and time-range queries, instead of hand-rolling the manual bucket pattern. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Financial tick/candle data (OHLCV) where downsampling with $dateTrunc and gap-filling with $densify/$fill matters for charting. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Infrastructure or observability metrics (CPU, memory, request latency) where rolling-average or p95 dashboards need bucket-level pruning to stay fast at scale. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Application event streams appended in timestamp order and queried mostly by recent time range, where storage cost (50-90% reduction via columnar compression) matters at high ingest volume. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Project ideas

Build an IoT ingestion pipeline that batches sensor readings by metaField (device ID) before insert, matching the batched-insertion pattern the pack calls out as critical for performance. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a Kafka Connector-based zero-downtime migration from a regular collection to a time series collection, dual-writing during cutover and verifying with a diff before draining the old connector. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a downsampling job using $dateTrunc plus $densify and $fill to turn raw tick-level data into gap-filled hourly OHLCV candles for a charting dashboard. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Build a tiered-TTL archival pattern (MongoDB 7.0+ partial filter) that expires raw high-resolution buckets sooner while retaining a downsampled long-term aggregate. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Antipatterns

Choosing timeField as (part of) the shard key: deprecated in MongoDB 8.0 because monotonically increasing values create write hotspots on a single shard; shard on metaField instead. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Setting metaField to a high-cardinality, unbounded value such as a UUID or per-request ID: every unique value opens its own bucket, exploding the working set and cache pressure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Picking a granularity that doesn't match the ingest rate: too coarse for high-frequency data hits the ~1,000-measurement/~125KB bucket cap before the time span does; too fine for low-frequency data closes buckets after ~1 measurement and destroys columnar compression. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Relying on Atlas Database Triggers or change streams for a time series collection: they aren't supported since the bucket storage format emits no per-document change events; use a dual-write to a regular collection or Atlas Stream Processing upstream instead. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

You cannot convert an existing collection to time series in place: migration always means creating a new time series collection and copying or streaming data across. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Unique indexes and text indexes are not supported on time series collections, and distinct() isn't efficiently supported, so dedup and full-text needs must move to the application layer, $group, or Atlas Search. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
TTL deletes whole buckets, not individual measurements, and deletion can lag by up to bucket-span plus 60 seconds past the last measurement's expiry, so a bucket with hours granularity spanning 30 days won't be removed until every measurement in it has expired. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Bucket span can only be increased via collMod after creation, never decreased, and timeField/metaField are permanently immutable once the collection is created. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

$dateTrunc Downsampling
$setWindowFields Window Functions
Time Series Collection Creation (timeField, metaField, granularity) (frontier, viability 4.08 / 5)
TTL and Automatic Bucket Deletion (frontier, viability 4.05 / 5)
Atlas Charts Integration (frontier, viability 2.70 / 5, below research gate)
Atlas Triggers Workarounds (no change streams) (frontier, viability 2.58 / 5, below research gate)
Time Series Sharding Patterns (frontier, viability 4.35 / 5)
Migration from Regular Collections (frontier, viability 3.75 / 5)
Granularity Anti-Patterns (frontier, viability 3.67 / 5)
MongoDB Time-Series Query and Index Optimization

Frontier under this node: Atlas Charts Integration (2.70), Atlas Triggers Workarounds (no change streams) (2.58), Bucket Architecture and Columnar Compression, Granularity Anti-Patterns (3.67), Migration from Regular Collections (3.75), MongoDB 8.0 Block Processing, Secondary Indexes on Time Series (4.00), TTL and Automatic Bucket Deletion (4.05), Time Series Collection Creation (timeField, metaField, granularity) (4.08), Time Series Sharding Patterns (4.35), Working Set Sizing for Time Series (3.20), metaField Cardinality Anti-Patterns (3.70)

← the whole tree · 3D view· how to read this page