diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index ca2a7348..babed0a7 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.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: diff --git a/source/data-formats.txt b/source/data-formats.txt index 5a05905c..ce4ca5d4 100644 --- a/source/data-formats.txt +++ b/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 -------- diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt new file mode 100644 index 00000000..7e7e7b6d --- /dev/null +++ b/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 ` +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 ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods mentioned in this guide, see the following +API documentation: + +- `create_collection() `__ +- `list_collections() `__ +- `insert_one() `__ +- `insert_many() `__