DOCSP-37513: Time Series Collections

.github/workflows/vale-tdbx.yml

@@ -12,6 +12,9 @@ jobs:
       - name: checkout
         uses: actions/checkout@v4
 
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
+
       - id: files
         uses: masesgroup/retrieve-changed-files@v2
         with:

source/data-formats.txt

@@ -24,6 +24,7 @@ Specialized Data Formats
    /data-formats/custom-types
    /data-formats/dates-and-times
    /data-formats/uuid
+   /data-formats/time-series
 
 Overview
 --------

source/data-formats/time-series.txt

@@ -0,0 +1,199 @@
+.. _pymongo-time-series:
+
+================
+Time Series Data
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use {+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
+
+.. _pymongo-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.
+
+To create a time series collection, pass the following arguments to the 
+``create_collection()`` method:
+
+- Name of the new collection to create
+- ``timeseries`` argument 
+
+The ``timeseries`` argument is of type ``dict``. It contains the following fields:
+
+- ``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 :manual:`Command Fields </reference/command/create/#command-fields>`
+to learn more about these fields.
+
+Example
+~~~~~~~
+
+The following example creates a time series collection named ``october2024`` with the
+``timeField`` option set to ``"timestamp"``:
+
+.. code-block:: python
+
+    database = client.get_database("weather")
+
+    time_series_options = {
+        "timeField": "timestamp"
+    }
+
+    database.create_collection("october2024", timeseries=time_series_options)
+
+To check if you successfully created the collection, you can get a list of all
+collections in your database and filter by collection name:
+
+.. io-code-block::
+    :copyable: true
+
+    .. input::
+        :language: python
+
+        print(list(database.list_collections(filter={'name': 'october2024'})))
+
+    .. output::
+        :language: json
+        :visible: false
+
+        {
+            "name": "october2024", 
+            "type": "timeseries", 
+            "options": {
+                "timeseries":   {
+                    "timeField": "timestamp",
+                    "granularity": "seconds", 
+                    "bucketMaxSpanSeconds": 3600
+                }
+            }, 
+            "info": {
+                "readOnly": False
+            }
+        }
+
+.. _pymongo-time-series-write:
+
+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.
+
+To learn more about inserting documents, see :ref:`pymongo-write-insert`.
+
+Example
+~~~~~~~
+
+This example inserts New York City temperature data into the ``october2024``
+time series collection created in :ref:`pymongo-time-series-create`. 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
+
+.. code-block:: python
+
+    from datetime import datetime
+
+    collection = database["october2024"]
+
+    document_list = [
+        { "temperature": 77, "location": "New York City", "timestamp": datetime(2024, 10, 22, 6, 0, 0) },
+        { "temperature": 74, "location": "New York City", "timestamp": datetime(2024, 10, 23, 6, 0, 0) }
+    ]
+
+    collection.insert_many(document_list)
+
+.. tip:: Formatting Dates and Times
+
+    To learn more about using ``datetime`` objects in {+driver-short+}, see 
+    :ref:`pymongo-dates-times`.
+
+.. _pymongo-time-series-read:
+
+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 :ref:`pymongo-read`
+and :ref:`pymongo-aggregation`.
+
+.. _pymongo-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts 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/>`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods mentioned in this guide, see the following
+API documentation:
+
+- `create_collection() <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/database.html#pymongo.database.Database.create_collection>`__
+- `list_collections() <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/database.html#pymongo.database.Database.list_collections>`__
+- `insert_one() <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/collection.html#pymongo.collection.Collection.insert_one>`__
+- `insert_many() <https://pymongo.readthedocs.io/en/4.10.1/api/pymongo/collection.html#pymongo.collection.Collection.insert_many>`__