> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Time Series

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**: Indicates when the data point was recorded.

- **Metadata**: A label or tag that identifies a data series and rarely changes. Metadata is stored in a `metaField`. You cannot add a `metaField` field to a time series document after you create it. Metadata is also known as `source`. For more information, see [metaFields.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-timeseries-collections-metafield)

- **Metrics**: Individual data points tracked at increments in time, often displayed as key-value pairs that change over time. Metrics are also known as values.

- **Measurements**: Documents that contain data for all metrics at a specific point in time. A measurement includes the time, metadata, and all metrics recorded at that moment.

This table shows examples of time series data:

| **Example** | **Metrics** | **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.

The following example shows a measurement document for weather data:

```javascript
{
  "timestamp": ISODate("2025-08-19T12:00:00Z"),
  "metaField": {
    "sensorId": "A1234",
    "location": {
      "city": "New York",
      "state": "NY"
    }
  },
  "temperature": 25.4,
  "humidity": 48.2,
  "pressure": 1012.5,
  "windSpeed": 5.2,
  "windDirection": "NW"
}
```

## Time Series Collections

**New in version 5.0**

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

You can [create time series collections in the UI](https://www.mongodb.com/docs/atlas/atlas-ui/collections.md#std-label-atlas-ui-create-a-collection) for deployments hosted in [MongoDB Atlas.](https://www.mongodb.com/docs/atlas)

**Important: Backwards-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.

### Benefits

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](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-secondary-index). MongoDB 6.3 and later automatically creates a [compound index](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-compound.md#std-label-index-type-compound) 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

### Example Use Cases

Time series collections are optimal for analyzing data over time. The following table illustrates use cases for time series data:

| Industry | Examples |
| --- | --- |
| Internet of Things (IoT) | Sensor data (for example, smart home devices or fleet logistics); Machine learning and artificial intelligence scraping |
| Financial Services | High frequency trading; Financial quantitative analysis; Banking data (for example, accounting of banking transactions over time); Stock market data |
| Retail and E-Commerce | Transaction, sales, and price analysis; Inventory management |
| DevOps | Application logging; Infrastructure and network monitoring |

Time series collections are not intended for the following types of data:

- Unordered data

- Data that is not time-dependent

### Behavior

Time series collections generally behave like other MongoDB collections.

**Warning:**

Match expressions in update commands can only specify the metaField. You can't update other fields in a time series document. For more details, see [Time Series Update Limitations.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-limitations.md#std-label-timeseries-limitations-updates)

Starting in 9.0, MongoDB stores time series collections in single namespaces that contain the data compressed into organized groups, or [buckets](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-bucketing.md#std-label-timeseries-bucketing-specifics). When you query a time series collection, MongoDB converts the data from its raw bucketed form to a logical form with one document per measurement.

Starting in MongoDB 6.3: if you create a new time series collection, MongoDB also generates a [compound index](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-compound/create-compound-index.md#std-label-index-create-compound) on the [metaField and timeField](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-procedures.md#std-label-time-series-fields) fields. To improve query performance, queries on time series collections use the new compound index. The compound index also uses the optimized storage format.

**Warning:**

Starting in MongoDB 8.0, shard keys containing the `timeField` are deprecated for time series collections.

Also, starting in MongoDB 8.0, if you create a time series collection with a shard key containing the `timeField`, a [log message](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref) is added to the [log file](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-message-destinations) on the [primary shard](https://www.mongodb.com/docs/manual/core/sharded-cluster-shards.md#std-label-primary-shard). In addition, a log message is added every 12 hours on the primary node of the [config server replica set](https://www.mongodb.com/docs/manual/core/sharded-cluster-config-servers.md#std-label-csrs). The log messages state that using the `timeField` as a shard key in a time series collection is deprecated and you must reshard your collection using the `metaField`.

### metaFields

Time series documents can contain a `metaField`. MongoDB uses the `metaField` to group documents for storage optimization and query efficiency. For more information about the `metaField`, see [metaField Considerations.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-considerations.md#std-label-timeseries-metafield-considerations)

### Indexes

MongoDB automatically creates a [compound index](https://www.mongodb.com/docs/manual/core/indexes/index-types/index-compound.md#std-label-index-type-compound) on both the metaField and timeField of a time series collection.

### Zone Sharding

Zone sharding does not support time series collections. The balancer always distributes data in sharded time series collections evenly across all shards in the cluster.

## Next Steps

To get started with time series collections, see the tutorials on the following pages:

- [Time Series Quick Start](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-quick-start.md#std-label-timeseries-quick-start)

- [Create and Query a Time Series Collection](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-procedures.md#std-label-timeseries-create-query-procedures)