Time Series Collection Limitations
On this page
- Unsupported Features
- Aggregation $merge and $out
- distinct Command
- Geospatial Queries
- 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
andmetaField
- 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.
Unsupported Features
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.
Aggregation $merge and $out
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.
distinct Command
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:
Creating a compound index on
meta.project
andmeta.type
and supports the aggregation.The
$match
stage filters for documents wheremeta.project = 10
.The
$group
stage usesmeta.type
as the group key to output one document per unique value.
Geospatial Queries
Time series collections only support the $geoNear
aggregation
stage for sorting geospatial data from queries
against 2dsphere indexes. The $near
and
$nearSphere
operators are not supported.
Document Size
The maximum size for documents within a time series collection is 4 MB.
Deletes
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 thedeleteMany()
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.
Updates
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 theupdateMany()
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.
Time Series Secondary Indexes
MongoDB 6.0 and later features improved support for secondary indexes on time series collections. For a summary of these options, see Time Series Indexes.
Time Series Secondary Indexes
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:
You can only create multikey indexes on the
metaField
.You can only create sparse indexes on the
metaField
.
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.
For more information, see setFeatureCompatibilityVersion
.
Time Series Secondary Indexes with MongoDB 5.0 and Earlier
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.
Capped Collections
You cannot create a time series collection as a capped collection.
Modification of Collection Type
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.
Modification of timeField
and metaField
You can only set a collection's timeField
and metaField
parameters when you create the collection. You cannot modify these
parameters later.
Granularity
Bucket Size
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.
Modifying Bucket Parameters
Once you set a collection's granularity
or the custom bucketing
parameters bucketMaxSpanSeconds
and bucketRoundingSeconds
, you
can increase the time span 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.
Sharding
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.
Sharding Administration Commands
You cannot run sharding administration commands on sharded time series collections.
Shard Key Fields
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:
metaField
can be either a:timeField
must be:At the end of the shard key pattern
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:
Starting in MongoDB 8.0, use of the timeField
as a shard key in a
time series collection is deprecated. Instead, reshard a collection with
the metaField
. For details, see
Shard a Time Series Collection.
Resharding
You cannot reshard a sharded time series collection. However, you can refine its shard key.
Transactions
You cannot write to time series collections in transactions.
Note
Reads from time series collections are supported in transactions.
Views
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
).
Snapshot Isolation
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.