From 523c579c2e42de1d04045bb7c1b941263d81713d Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 16:15:02 -0400 Subject: [PATCH 1/6] DOCSP-41964: Time series collections --- source/databases-collections.txt | 11 + source/databases-collections/time-series.txt | 208 ++++++++++++++++++ .../databases-collections/time-series.php | 48 ++++ 3 files changed, 267 insertions(+) create mode 100644 source/databases-collections.txt create mode 100644 source/databases-collections/time-series.txt create mode 100644 source/includes/databases-collections/time-series.php diff --git a/source/databases-collections.txt b/source/databases-collections.txt new file mode 100644 index 00000000..13628e9b --- /dev/null +++ b/source/databases-collections.txt @@ -0,0 +1,11 @@ +.. _php-databases-collections: + +========================= +Databases and Collections +========================= + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /databases-collections/time-series \ No newline at end of file diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt new file mode 100644 index 00000000..98ea0083 --- /dev/null +++ b/source/databases-collections/time-series.txt @@ -0,0 +1,208 @@ +.. _php-time-series: + +================ +Time Series Data +================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +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 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 + +.. _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, specify the following fields: + +- ``timeField``: The field that stores a timestamp in each time series document. +- ``metaField``: The field that stores metadata in each time series document. +- ``granularity``: 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 ``.system.buckets`` namespace. For more information, + see :manual:`.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 +`. 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 ` 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 ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +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()` diff --git a/source/includes/databases-collections/time-series.php b/source/includes/databases-collections/time-series.php new file mode 100644 index 00000000..a3a65ac4 --- /dev/null +++ b/source/includes/databases-collections/time-series.php @@ -0,0 +1,48 @@ +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 From 497cc4eae764745a54bcf82c95db45f066d79e47 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 16:19:29 -0400 Subject: [PATCH 2/6] toc --- source/index.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/source/index.txt b/source/index.txt index b4b4841a..dc7ad712 100644 --- a/source/index.txt +++ b/source/index.txt @@ -11,6 +11,7 @@ MongoDB PHP Library :titlesonly: Get Started + /databases-collections /read /write /aggregation From 92d5a0346e5c5c658d963c969654f18c922d60c9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 16:25:22 -0400 Subject: [PATCH 3/6] edits --- source/databases-collections/time-series.txt | 16 ++++++++-------- source/tutorial/crud.txt | 2 -- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt index 98ea0083..0257e742 100644 --- a/source/databases-collections/time-series.txt +++ b/source/databases-collections/time-series.txt @@ -1,8 +1,8 @@ .. _php-time-series: -================ -Time Series Data -================ +======================= +Time Series Collections +======================= .. default-domain:: mongodb @@ -60,11 +60,11 @@ Create a Time Series Collection 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, specify the following fields: +``timeseries`` option. When setting this option, include the following fields: -- ``timeField``: The field that stores a timestamp in each time series document. -- ``metaField``: The field that stores metadata in each time series document. -- ``granularity``: The approximate time between consecutive timestamps. The possible +- ``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: @@ -135,7 +135,7 @@ print the results: MongoDB stores system data associated with time series collections in the ``.system.buckets`` namespace. For more information, - see :manual:`.system.buckets ` + see :manual:`database.system.buckets ` in the {+mdb-server+} manual. .. _php-time-series-insert: diff --git a/source/tutorial/crud.txt b/source/tutorial/crud.txt index a69ec662..036e176f 100644 --- a/source/tutorial/crud.txt +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 816a625a803fa79edfde210d95bd212c3969a8c4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Sep 2024 16:31:34 -0400 Subject: [PATCH 4/6] keywords --- source/databases-collections/time-series.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt index 0257e742..0551c138 100644 --- a/source/databases-collections/time-series.txt +++ b/source/databases-collections/time-series.txt @@ -4,14 +4,19 @@ Time Series Collections ======================= -.. default-domain:: mongodb - .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: chronological, data format, code example + Overview -------- From 619d9dd2a19c4e266dfed83d6ee1fa223d6a39c5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Sep 2024 16:18:54 -0400 Subject: [PATCH 5/6] SA feedback --- source/databases-collections/time-series.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt index 0551c138..9c21e2e3 100644 --- a/source/databases-collections/time-series.txt +++ b/source/databases-collections/time-series.txt @@ -28,7 +28,7 @@ time series data, which is composed of the following components: - Timestamp for the measurement - Metadata that describes the measurement -The following table describes sample situations for which you could store time +The following table describes sample situations for which you can store time series data: .. list-table:: From 728baf9082c78530bf3d007b5496b7470f88577c Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Sep 2024 11:25:32 -0400 Subject: [PATCH 6/6] JT feedback --- source/includes/databases-collections/time-series.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/includes/databases-collections/time-series.php b/source/includes/databases-collections/time-series.php index a3a65ac4..35b005e2 100644 --- a/source/includes/databases-collections/time-series.php +++ b/source/includes/databases-collections/time-series.php @@ -1,7 +1,7 @@ [ 'timeField' => 'timestamp', 'metaField' => 'location', - 'granularity' => 'minutes' + 'granularity' => 'minutes', ] ]; @@ -36,13 +36,13 @@ [ 'precipitation_mm' => 0.5, 'location' => 'New York City', - 'timestamp' => new MongoDB\BSON\UTCDateTime(1694829060000) + 'timestamp' => new MongoDB\BSON\UTCDateTime(1694829060000), ], [ 'precipitation_mm' => 2.8, 'location' => 'New York City', - 'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000) - ] + 'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000), + ], ] ); // end-insert-ts