DOCSP-41964: Time series collections

source/databases-collections.txt

@@ -0,0 +1,11 @@
+.. _php-databases-collections:
+
+=========================
+Databases and Collections
+=========================
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /databases-collections/time-series

source/databases-collections/time-series.txt

@@ -0,0 +1,213 @@
+.. _php-time-series:
+
+=======================
+Time Series Collections
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: chronological, data format, code example
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+php-library+} to create
+and interact with **time series collections**. These collections store
+time series data, which 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 can 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
+
+.. _php-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 an options array to the 
+``MongoDB\Database::createCollection()`` method that sets the
+``timeseries`` option. When setting this option, include 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'``.
+
+.. _php-time-series-create-example:
+
+Example
+~~~~~~~
+
+This example creates the ``sept2023`` time series collection in the
+``precipitation`` database with the following configuration:
+
+- ``timeField`` is set to ``'timestamp'``
+- ``metaField`` is set to ``'location'``
+- ``granularity`` is set to ``'minutes'``
+
+.. literalinclude:: /includes/databases-collections/time-series.php
+   :start-after: start-create-ts
+   :end-before: end-create-ts
+   :language: php
+   :dedent:
+
+To verify that you successfully created the time series collection, call
+the ``MongoDB\Database::listCollections()`` method on the database and
+print the results:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/databases-collections/time-series.php
+      :start-after: start-list-colls
+      :end-before: end-list-colls
+      :language: php
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      MongoDB\Model\CollectionInfo Object
+      (
+          [name] => sept2023
+          [type] => timeseries
+          [options] => Array
+              (
+                  …
+              )
+
+          [info] => Array
+              (
+                  …
+              )
+      )
+      MongoDB\Model\CollectionInfo Object
+      (
+          [name] => system.buckets.sept2023
+          [type] => collection
+          [options] => Array
+              (
+                  …
+              )
+
+          [info] => Array
+              (
+                  …
+              )
+      )
+
+.. note::
+
+    MongoDB stores system data associated with time series collections
+    in the ``<database>.system.buckets`` namespace. For more information,
+    see :manual:`database.system.buckets </reference/system-collections/#mongodb-data--database-.system.buckets>`
+    in the {+mdb-server+} manual.
+
+.. _php-time-series-insert:
+
+Insert Time Series Data
+-----------------------
+
+You can insert data into a time series collection by using the ``MongoDB\Collection::insertOne()``
+or ``MongoDB\Collection::insertMany()`` methods and specifying the measurement,
+timestamp, and metadata in each inserted document.
+
+.. tip::
+
+   To learn more about inserting documents into a collection, see the :ref:`php-write-insert`
+   guide.
+
+Example
+~~~~~~~
+
+This example inserts New York City precipitation data into the ``sept2023``
+time series collection created in the :ref:`Create a Time Series Collection example
+<php-time-series-create-example>`. Each document contains the following fields:
+
+- ``precipitation_mm``, which stores precipitation measurements in millimeters
+- ``location``, which stores location metadata
+- ``timestamp``, which stores the time of the measurement collection
+
+.. literalinclude:: /includes/databases-collections/time-series.php
+   :start-after: start-insert-ts
+   :end-before: end-insert-ts
+   :language: php
+   :dedent:
+
+.. _php-time-series-query:
+
+Query Time Series Collections
+-----------------------------
+
+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 find more information about these operations, see
+the :ref:`Additional Information <php-time-series-addtl-info>` section.
+
+.. _php-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the
+following 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:`php-read`.
+
+To learn more about performing aggregation operations, see the :ref:`php-aggregation`
+guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods mentioned in this guide, see the following
+API documentation:
+
+- :phpmethod:`MongoDB\Database::createCollection()`
+- :phpmethod:`MongoDB\Database::listCollections()`
+- :phpmethod:`MongoDB\Collection::insertOne()`
+- :phpmethod:`MongoDB\Collection::insertMany()`

source/includes/databases-collections/time-series.php

@@ -0,0 +1,48 @@
+<?php
+require 'vendor/autoload.php'; 
+
+$uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
+$client = new MongoDB\Client($uri);
+
+// Creates a time series collection to store precipitation data
+// start-create-ts
+$db = $client->precipitation;
+
+$options = [
+    'timeseries' => [
+        'timeField' => 'timestamp',
+        'metaField' => 'location',
+        'granularity' => 'minutes'
+    ]
+];
+
+$collection = $db->createCollection('sept2023', $options);
+// end-create-ts
+
+// Lists the collections in the "precipitation" database
+// start-list-colls
+$cursor = $db->listCollections();
+
+foreach ($cursor as $collectionInfo) {
+    print_r($collectionInfo) . PHP_EOL;
+}
+// end-list-colls
+
+// Inserts precipitation time series data about New York City into the collection
+// start-insert-ts
+$collection = $db->sept2023;
+$result = $collection->insertMany(
+    [
+        [
+            'precipitation_mm' => 0.5,
+            'location' => 'New York City',
+            'timestamp' => new MongoDB\BSON\UTCDateTime(1694829060000)
+        ],
+        [
+            'precipitation_mm' => 2.8,
+            'location' => 'New York City',
+            'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000)
+        ]
+    ]
+);
+// end-insert-ts

source/index.txt

@@ -11,6 +11,7 @@ MongoDB PHP Library
    :titlesonly:
 
    Get Started </get-started>
+   /databases-collections
    /read
    /write
    /aggregation

source/tutorial/crud.txt

@@ -414,8 +414,6 @@ following example finds restaurants whose name starts with "(Library)":
        'name' => new MongoDB\BSON\Regex('^' . preg_quote('(Library)')),
    ]);
 
-.. _php-aggregation:
-
 Complex Queries with Aggregation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~