Time Series Data
On this page
Overview
In this guide, you can learn how to use the C++ 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.
You can create a time series collection to store time series data. To create a time series collection, perform the following actions:
Create a BSON document that specifies the properties of your time series collection.
Call the
create_collection()
method and pass the collection name and the time series BSON document as arguments.
Example
This example creates the sept2023
time series collection in the
precipitation
database with the following configuration:
timeField
is set to"timestamp"
metaField
is set to"location"
granularity
is set to"minutes"
auto db = client["precipitation"]; auto ts_info = make_document( kvp("timeseries", make_document( kvp("timeField", "timestamp"), kvp("metaField", "location"), kvp("granularity", "minutes") ))); auto collection = db.create_collection("sept2023", ts_info.view());
To verify that you successfully created the time series collection, run
the list_collections()
method on the database and print the results:
auto cursor = db.list_collections(); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "name" : "sept2023", "type" : "timeseries", "options" : { "timeseries" : { "timeField" : "timestamp", "metaField" : "location", "granularity" : "minutes", "bucketMaxSpanSeconds" : 86400 } }, "info" : ... }
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.
Tip
To learn more about inserting documents into a collection, see the Insert Documents guide.
Example
This example inserts New York City precipitation data into the sept2023
time series collection created in the Create a Time Series Collection example. Each document contains the following fields:
precipitation_mm
, which stores precipitation measurements in millimeterslocation
, which stores location metadatatimestamp
, which stores the time of the measurement collection
auto collection = db["sept2023"]; std::vector<bsoncxx::document::value> ts_data; ts_data.push_back(make_document(kvp("precipitation_mm", 0.5), kvp("location", "New York City"), kvp("timestamp", bsoncxx::types::b_date{std::chrono::milliseconds{1694829060000}}))); ts_data.push_back(make_document(kvp("precipitation_mm", 2.8), kvp("location", "New York City"), kvp("timestamp", bsoncxx::types::b_date{std::chrono::milliseconds{1695594780000}}))); auto result = collection.insert_many(ts_data);
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 find more information about these operations, see the Additional Information section.
Additional Information
To learn more about the concepts mentioned in this guide, see the following Server manual entries:
To learn more about performing read operations, see Read Data from MongoDB.
To learn more about performing aggregation operations, see the Transform Your Data with Aggregation guide.
API Documentation
To learn more about the methods mentioned in this guide, see the following API documentation: