Docs Menu
Docs Home
/
MongoDB Manual

Time Series

On this page

  • Time Series Collections
  • Benefits
  • Behavior
  • metaFields
  • Get Started

Time series data is a sequence of data points in which insights are gained by analyzing changes over time.

Time series data is generally composed of these components:

  • Time when the data point was recorded.

  • metadata (sometimes referred to as source), which is a label or tag that identifies a data series and rarely changes. Metadata is stored in a metaField. You cannot add metaFields to time series documents after you create them. For more information on metaField behavior and selection, see metaFields.

  • Measurements (sometimes referred to as metrics or values), which are the data points tracked at increments in time. Generally these are key-value pairs that change over time.

This table shows examples of time series data:

Example
Measurement
Metadata
Stock data
Stock price
Stock ticker, exchange
Weather data
Temperature
Sensor identifier, location
Website visitors
View count
URL

For efficient time series data storage, MongoDB provides time series collections.

New in version 5.0.

Time series collections efficiently store time series data. In time series collections, writes are organized so that data from the same source is stored alongside other data points from a similar point in time.

Compared to normal collections, storing time series data in time series collections improves query efficiency and reduces the disk usage for time series data and secondary indexes. MongoDB 6.3 and later automatically creates a compound index on the time and metadata fields for new time series collections.

Time series collections use an underlying columnar storage format and store data in time-order. This format provides the following benefits:

  • Reduced complexity for working with time series data

  • Improved query efficiency

  • Reduced disk usage

  • Reduced I/O for read operations

  • Increased WiredTiger cache usage

Time series collections generally behave like other MongoDB collections. You insert and query data as usual.

Warning

Match expressions in update and delete commands can only specify the metaField. You can't update other fields in a time series document. For more details, see Time Series Delete and Update Limitations.

MongoDB treats time series collections as writable non-materialized views backed by an internal collection. When you insert data, the internal collection automatically organizes time series data into an optimized storage format.

Starting in MongoDB 6.3: if you create a new time series collection, MongoDB also generates a compound index on the metaField and timeField fields. To improve query performance, queries on time series collections use the new compound index. The compound index also uses the optimized storage format.

Tip

To improve query performance, you can manually add secondary indexes on measurement fields or any field in your time series collection.

Important

Backward-Incompatible Feature

You must drop time series collections before downgrading:

  • MongoDB 6.0 or later to MongoDB 5.0.7 or earlier.

  • MongoDB 5.3 to MongoDB 5.0.5 or earlier.

Warning

Do not attempt to create a time series collection or view with the name system.profile. MongoDB 6.3 and later versions return an IllegalOperation error if you attempt to do so. Earlier MongoDB versions crash.

Time series documents can contain an optional metaField to group sets of documents, both for internal storage optimization and query efficiency. A metaField should rarely change and can be any data type. A metaField can be an object and can contain subfields. Once you define a field as the metaField, you can change the value of the metaField but you cannot redefine the metaField as another field. For example, if you create time series documents with the metaField defined as field A, you cannot later convert a field B to be the metaField. However, if the value of metaField A is an object, you can add new subfields to field A.

Note

Using an array as a metaField may cause unexpected collection behavior because array equality depends on specific order.

MongoDB uses the metaField to partition data for efficient organization and retrieval. When you create a time series collection, MongoDB groups documents into buckets. Documents within a bucket share an identical metaField value and have timeField values that are close together.

The number of buckets in a time series collection depends on the number of unique metaField values. Collections with fine-grained or dynamic metaField values may generate more, sparsely packed, short-lived buckets than collections with simple metaFields that rarely or never change. Fine-grained and dynamic metaField values typically decrease storage and query effiency.

MongoDB automatically creates a compound index on both the metaField and timeField of a time series collection.

  • Select fields that rarely or never change as part of your metaField.

  • If possible, select identifiers or other stable values that are common in filter expressions as part of your metaField.

  • Avoid selecting fields that are not used for filtering as part of your metaField. Instead, use those fields as measurements.

To get started with time series collections, see Create and Query a Time Series Collection.

Back

Reference