DOCSP-43063 Time Series Data (#55)

snooty.toml

@@ -8,6 +8,7 @@ intersphinx = [
 ]
 
 toc_landing_pages = [
+  "/databases-collections",
   "/read", 
   "/get-started", 
   "/indexes", 

source/databases-collections.txt

@@ -17,6 +17,12 @@ Databases and Collections
 .. meta::
    :keywords: table, row, organize, storage
 
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /databases-collections/time-series
+
 Overview
 --------
 

source/databases-collections/time-series.txt

@@ -0,0 +1,169 @@
+.. _c-time-series:
+
+================
+Time Series Data
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, measurement, weather
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} 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:
+
+.. list-table::
+   :widths: 33, 33, 33
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - 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
+
+.. _c-time-series-create:
+
+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 {+mdb-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
+
+.. _c-time-series-create-example:
+
+The following example creates a time series collection named ``october2024`` in the
+``fall_weather`` database with the ``timeField`` option set to the ``"timestamp"`` fields:
+
+.. literalinclude:: /includes/databases-collections/timeseries.c
+   :language: c
+   :start-after: start-create-time-series
+   :end-before: end-create-time-series
+   :dedent:
+   :emphasize-lines: 13-19
+
+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:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/databases-collections/timeseries.c
+      :language: c
+      :start-after: start-list-collections
+      :end-before: end-list-collections
+      :dedent:
+      :emphasize-lines: 4-11
+
+   .. output::
+
+      { "name" : "october2024", "type" : "timeseries", "options" : { "timeseries" : { "timeField" : "timestamp", "granularity" : "seconds", "bucketMaxSpanSeconds" : { "$numberInt" : "3600" } } }, "info" : { "readOnly" : false } }
+      ...
+
+.. _c-time-series-store:
+
+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 :ref:`c-write-insert`
+guide.
+
+Example
+~~~~~~~
+
+The following example inserts New York City temperature data into the ``october2024``
+time series collection created in the :ref:`Create a Time Series Collection example
+<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
+
+.. literalinclude:: /includes/databases-collections/timeseries.c
+   :language: c
+   :start-after: start-insert-document
+   :end-before: end-insert-document
+   :dedent:
+
+.. _c-time-series-query:
+
+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 :ref:`Additional Information <c-time-series-addtl-info>` section.
+
+.. _c-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the
+following {+mdb-server+} manual entries:
+
+- :manual:`Time Series </core/timeseries-collections/>`
+- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
+- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
+
+To learn more about performing read operations, see :ref:`c-read`.
+
+To learn more about performing aggregation operations, see the :ref:`c-aggregation`
+guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the functions mentioned in this guide, see the following
+API documentation:
+
+- `mongoc_database_create_collection() <{+api-libmongoc+}/mongoc_database_create_collection.html#mongoc-database-create-collection>`__
+- `mongoc_database_find_collections_with_opts() <{+api-libmongoc+}/mongoc_database_find_collections_with_opts.html>`__
+- `mongoc_collection_insert_one() <{+api-libmongoc+}/mongoc_collection_insert_one.html#mongoc-collection-insert-one>`__

source/includes/databases-collections/timeseries.c

@@ -0,0 +1,69 @@
+#include <bson/bson.h>
+#include <mongoc/mongoc.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int main (void)
+{
+    // start-create-time-series
+    // 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);
+    // end-create-time-series
+
+    // start-list-collections
+    // 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);
+    // end-list-collections
+
+    // start-insert-document
+    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);
+    }
+    // end-insert-document
+    mongoc_database_destroy (database);
+    mongoc_client_destroy (client);
+    mongoc_collection_destroy (collection);
+    mongoc_cleanup ();
+
+    return EXIT_SUCCESS;
+}