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 Ruby driver 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, you must pass an options hash that contains the specifications for the collection. You can specify the following specifications for your time series collection:

: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 in the MongoDB Server manual entry on the create command to learn more about these parameters.

Example

The following example uses the Collection#create method to create a time series collection named october2024 with the :timeField` option set to "timestamp":

client = Mongo::Client.new('<connection string>', database: 'weather')
collection_name = 'october2024'
time_series_options = { timeField: 'timestamp' }
database = client.database
database.command(
  create: collection_name,
  timeseries: time_series_options
)

To verify that you have successfully created the collection, print a list of all collections in your database and filter by collection name, as shown in the following code:

collections = database.list_collections(filter: { name: 'october2024' }).to_a
puts collections

[
  {
    "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 method and specifying the measurement, timestamp, and metadata in each inserted document.

To learn more about inserting documents, see the Insert Documents guide.

Example

This example inserts New York City temperature data into the october2024 time series collection created in the preceding Create a Time Series Collection section. 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

client = Mongo::Client.new('<connection string>', database => 'your_db')
collection = client[:october2024]
document_list = [
  { temperature: 77, location: "New York City", timestamp: DateTime.new(2024, 10, 22, 6, 0, 0) },
  { temperature: 74, location: "New York City", timestamp: DateTime.new(2024, 10, 23, 6, 0, 0) }
]
collection.insert_many(document_list)

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 the following guides:

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

Data Formats

BSON