Docs Menu
Docs Home
/
MongoDB Manual
/ /

Time Series Collection Limitations

On this page

  • Unsupported Features
  • Aggregation $merge and $out
  • distinct Command
  • Document Size
  • Deletes
  • Updates
  • Time Series Secondary Indexes
  • Time Series Secondary Indexes
  • Time Series Secondary Indexes with MongoDB 5.0 and Earlier
  • Capped Collections
  • Modification of Collection Type
  • Modification of timeField and metaField
  • Granularity
  • Bucket Size
  • Modifying Bucket Parameters
  • Sharding
  • Sharding Administration Commands
  • Shard Key Fields
  • Resharding
  • Transactions
  • Views
  • Snapshot Isolation

This page describes limitations on using time series collections.

The following features are not supported for time series collections:

Atlas Device Sync support is limited to time series collections that use Atlas Data Ingest.

You cannot use the $merge aggregation stage to add data from another collection to a time series collection.

Changed in version 7.0.3: You can use the $out aggregation stage to write documents to a time series collection.

Due to the unique data structure of time series collections, MongoDB can't efficiently index them for distinct values. Avoid using the distinct command or db.collection.distinct() helper method on time series collections. Instead, use a $group aggregation to group documents by distinct values.

For example, to query for distinct meta.type values on documents where meta.project = 10, instead of:

db.foo.distinct("meta.type", {"meta.project": 10})

Use:

db.foo.createIndex({"meta.project":1, "meta.type":1})
db.foo.aggregate([{$match: {"meta.project": 10}},
{$group: {_id: "$meta.type"}}])

This works as follows:

  1. Creating a compound index on meta.project and meta.type and supports the aggregation.

  2. The $match stage filters for documents where meta.project = 10.

  3. The $group stage uses meta.type as the group key to output one document per unique value.

The maximum size for documents within a time series collection is 4 MB.

Starting in MongoDB 5.1, you can perform limited delete operations on time series collections. MongoDB 7.0 removes most limitations from operations that are based on the delete command.

Time series deletes are not supported for multi-document transactions.

From MongoDB 5.1 to 6.3, delete commands must meet the following requirements:

  • You can only match on metaField field values.

  • Your delete command must not limit the number of documents to be deleted. Set justOne: false or use the deleteMany() method.

Starting in MongoDB 7.0, there is only one time series related limitation on these delete commands:

You cannot use these commands with multi-document transactions. There are no other restrictions.

If a time series collection contains documents with timeField timestamps before 1970-01-01T00:00:00.000Z or after 2038-01-19T03:14:07.000Z, no documents are deleted from the collection by the TTL "time to live" feature.

For details on TTL deletes, see Expire Data from Collections by Setting TTL.

Starting in MongoDB 5.1, you can perform limited update operations.

Update commands must meet the following requirements:

  • You can only match on the metaField field value.

  • You can only modify the metaField field value.

  • Your update document can only contain update operator expressions.

  • Your update command must not limit the number of documents to be updated. Set multi: true or use the updateMany() method.

  • Your update command must not set upsert: true.

In MongoDB 5.0, time series collections only support insert operations and read queries. Updates and manual delete operations result in an error.

To automatically delete old data, set up automatic removal (TTL).

To remove all documents from a collection, use the drop() method to drop the collection.

MongoDB 6.0 and later features improved support for secondary indexes on time series collections. For a summary of these options, see Time Series Secondary Indexes in MongoDB 6.0 and Later.

Starting in MongoDB 6.3, time series collections support the expireAfterSeconds index property for partial indexes on the metaField. For earlier versions of MongoDB, use the collection level expireAfterSeconds parameter.

Starting in MongoDB 6.0, you can add a secondary index to any field.

These index types are partially supported:

These index types aren't supported:

If there are secondary indexes on time series collections and you need to downgrade the feature compatibility version (fCV), you must first drop any secondary indexes that are incompatible with the downgraded fCV. See setFeatureCompatibilityVersion.

In MongoDB 5.0 and earlier:

  • The metaField can have secondary indexes.

  • The timeField can have secondary indexes.

  • If the metaField is a document, you can add secondary indexes on fields inside the document.

Tip

See also:

You cannot create a time series collection as a capped collection.

You can only set the collection type when you create a collection:

  • An existing collection cannot be converted into a time series collection.

  • A time series collection cannot be converted into a different collection type.

To move data from an existing collection to a time series collection, migrate data into a time series collection.

You can only set a collection's timeField and metaField parameters when you create the collection. You cannot modify these parameters later.

For any configuration of granularity parameters, the maximum size of a bucket is 1000 measurements or 125KB of data, whichever is lower. MongoDB may also enforce a lower maximum size for high cardinality data with many unique values, so that the working set of buckets fits within the WiredTiger cache.

Once you set a collection's granularity or the custom bucketing parameters bucketMaxSpanSeconds and bucketRoundingSeconds, you can increase the timespan covered by a bucket, but not decrease it. Use the collMod command to modify the parameters. For example:

db.runCommand({
collMod: "timeseries",
timeseries: { bucketMaxSpanSeconds: 3600, bucketRoundingSeconds: 3600 }
})

Note

bucketMaxSpanSeconds and bucketRoundingSeconds must be equal. If you modify one parameter, you must also set the other to the same value.

Starting in MongoDB 5.1 (and 5.0.6), you can create sharded time series collections.

In versions earlier than MongoDB 5.0.6, you cannot shard time series collections.

You cannot run sharding administration commands on sharded time series collections.

When sharding time series collections, you can only specify the following fields in the shard key:

  • The metaField

  • Sub-fields of metaField

  • The timeField

You may specify combinations of these fields in the shard key. No other fields, including _id, are allowed in the shard key pattern.

When you specify the shard key:

Tip

Avoid specifying only the timeField as the shard key. Since the timeField increases monotonically, it may result in all writes appearing on a single chunk within the cluster. Ideally, data is evenly distributed across chunks.

To learn how to best choose a shard key, see:

You cannot reshard a sharded time series collection. However, you can refine its shard key.

You cannot write to time series collections in transactions.

Note

Reads from time series collections are supported in transactions.

  • Time series collections are writable non-materialized views. Limitations for views apply to time series collections.

  • You cannot create a view from a time series bucket collection namespace (namely, a collection prefixed with system.buckets).

Read operations on time series collections with read concern "snapshot" guarantee snapshot isolation only in the absence of concurrent drop or rename operations on collections in the read operation. Re-creating a time series collection on the same namespace with different granularity setting does not yield full snapshot isolation.

Back

Time Series Compression