Time Series Data

On this page

Overview

Create a Time Series Collection
Store Time Series Data
Query Time Series Data
Additional Information

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, pass the following parameters to the mongoc_database_create_collection() function:

The database in which to create the collection
The name of the new collection to create
A timeseries object that specifies the timeField option

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

// Initialize the MongoDB C Driver
mongoc_init ();
// Create a new client instance
mongoc_client_t *client = mongoc_client_new ("<connection string>");
// Get a handle on the database
mongoc_database_t *database = mongoc_client_get_database (client, "fall_weather");
// Create options for the time series collection
bson_t *opts = BCON_NEW (
    "timeseries", "{",
    "timeField", BCON_UTF8 ("timestamp"),
    "}");
// Create the time series collection
bson_error_t error;
mongoc_collection_t *collection = mongoc_database_create_collection (database, "october2024", opts, &error);
if (!collection) {
    fprintf(stderr, "Error creating collection: %s\n", error.message);
}
bson_destroy (opts);

To verify that you successfully created the time series collection, run the mongoc_database_find_collections_with_opts() function on the fall_weather database and print the results:

// List collections in the database
mongoc_cursor_t *cursor = mongoc_database_find_collections_with_opts (database, NULL);
const bson_t *doc;
while (mongoc_cursor_next (cursor, &doc))
{
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
// Check for cursor errors
if (mongoc_cursor_error (cursor, &error))
{
    fprintf (stderr, "Cursor error: %s\n", error.message);
}
mongoc_cursor_destroy (cursor);

{ "name" : "october2024", "type" : "timeseries", "options" : { "timeseries" : { "timeField" : "timestamp", "granularity" : "seconds", "bucketMaxSpanSeconds" : { "$numberInt" : "3600" } } }, "info" : { "readOnly" : false } }
...

Store Time Series Data

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

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

Example

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

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

const bson_t *insert_doc = BCON_NEW (
    "temperature", BCON_DOUBLE (70.0),
    "location", "{", "city", BCON_UTF8 ("New York"), "}",
    "timestamp", BCON_DATE_TIME (1633046400000));
if (!mongoc_collection_insert_one (collection, insert_doc, NULL, NULL, &error)) {
    fprintf(stderr, "Error inserting document: %s\n", error.message);
}

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 Additional Information section.

Additional Information

To learn more about the concepts mentioned in this guide, see the following MongoDB 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 functions mentioned in this guide, see the following API documentation:

Back

Databases & Collections

Run a Database Command