Time Series Data

On this page

Overview

Create a Time Series Collection
Example
Store Time Series Data
Example
Query Time Series Data
Additional Information
API Documentation

Overview

In this guide, you can learn how to use PyMongo to store and interact with time series data.

Time series data is composed of the following components:

Measured quantity
Timestamp for the measurement
Metadata that describes the measurement

The following table describes sample situations for which you could store time series data:

Situation	Measured Quantity	Metadata
Recording monthly sales by industry	Revenue in USD	Company, country
Tracking weather changes	Precipitation level	Location, sensor type
Recording fluctuations in housing prices	Monthly rent price	Location, currency

Create a Time Series Collection

Important

Server Version for Time Series Collections

To create and interact with time series collections, you must be connected to a deployment running MongoDB Server 5.0 or later.

To create a time series collection, pass the following arguments to the create_collection() method:

Name of the new collection to create
timeseries argument

The timeseries argument is of type dict. It contains the following fields:

timeField: Specifies the field that stores a timestamp in each time series document.
metaField: Specifies the field that stores metadata in each time series document.
granularity: Specifies the approximate time between consecutive timestamps. The possible values are 'seconds', 'minutes', and 'hours'.
bucketMaxSpanSeconds: Sets the maximum time between timestamps in the same bucket.
bucketRoundingSeconds: Sets the number of seconds to round down by when MongoDB sets the minimum timestamp for a new bucket. Must be equal to bucketMaxSpanSeconds.

See Command Fields to learn more about these fields.

Example

The following example creates a time series collection named october2024 with the timeField option set to "timestamp":

database = client.get_database("weather")
time_series_options = {
    "timeField": "timestamp"
}
database.create_collection("october2024", timeseries=time_series_options)

To check if you successfully created the collection, you can get a list of all collections in your database and filter by collection name:

print(list(database.list_collections(filter={'name': 'october2024'})))

{
    "name": "october2024",
    "type": "timeseries",
    "options": {
        "timeseries":   {
            "timeField": "timestamp",
            "granularity": "seconds",
            "bucketMaxSpanSeconds": 3600
        }
    },
    "info": {
        "readOnly": False
    }
}

Store Time Series Data

You can insert data into a time series collection by using the insert_one() or insert_many() methods and specifying the measurement, timestamp, and metadata in each inserted document.

To learn more about inserting documents, see Insert Documents.

Example

This example inserts New York City temperature data into the october2024 time series collection created in Create a Time Series Collection. Each document contains the following fields:

temperature, which stores temperature measurements in degrees Fahrenheit
location, which stores location metadata
timestamp, which stores the measurement timestamp

from datetime import datetime
collection = database["october2024"]
document_list = [
    { "temperature": 77, "location": "New York City", "timestamp": datetime(2024, 10, 22, 6, 0, 0) },
    { "temperature": 74, "location": "New York City", "timestamp": datetime(2024, 10, 23, 6, 0, 0) }
]
collection.insert_many(document_list)

Tip

Formatting Dates and Times

To learn more about using datetime objects in PyMongo, see Dates and Times.

Query Time Series Data

You can use the same syntax and conventions to query data stored in a time series collection as you use when performing read or aggregation operations on other collections. To learn more about these operations, see Read Data from MongoDB and Transform Your Data with Aggregation.

Additional Information

To learn more about the concepts in this guide, see the following MongoDB Server manual entries:

API Documentation

To learn more about the methods mentioned in this guide, see the following API documentation:

Back

Universally Unique IDs (UUIDs)

Third-Party Tools