Time Series Data

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

Time Series Data

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:

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);

Output:

{ "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](https://www.mongodb.com/docs/languages/c/c-driver/current/crud/insert.md#std-label-c-write-insert 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](https://www.mongodb.com/docs/languages/c/c-driver/current/data-formats/time-series.md#std-label-c-time-series-create-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](https://www.mongodb.com/docs/languages/c/c-driver/current/data-formats/time-series.md#std-label-c-time-series-addtl-info section.

Additional Information

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

• Time Series

• Create and Query a Time Series Collection

• Set Granularity for Time Series Data

To learn more about performing read operations, see [Read Data.](https://www.mongodb.com/docs/languages/c/c-driver/current/crud/query-operations.md#std-label-c-read

To learn more about performing aggregation operations, see the [Aggregation](https://www.mongodb.com/docs/languages/c/c-driver/current/aggregation.md#std-label-c-aggregation guide.

API Documentation

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

• [mongoc_database_create_collection()](https://mongoc.org/libmongoc/current/mongoc_database_create_collection.html#mongoc-database-create-collection

• mongoc_database_find_collections_with_opts()

• [mongoc_collection_insert_one()](https://mongoc.org/libmongoc/current/mongoc_collection_insert_one.html#mongoc-collection-insert-one