diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 1a650dc9..f031a006 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -17,6 +17,12 @@ Databases and Collections .. meta:: :keywords: table, row, organize, storage, code example +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /databases-collections/time-series + Overview -------- @@ -319,4 +325,4 @@ guide, see the following API documentation: - :phpmethod:`MongoDB\Database::selectCollection()` - :phpmethod:`MongoDB\Database::createCollection()` - :phpmethod:`MongoDB\Database::listCollections()` -- :phpmethod:`MongoDB\Database::dropCollection()` \ No newline at end of file +- :phpmethod:`MongoDB\Database::dropCollection()` diff --git a/source/databases-collections/time-series.txt b/source/databases-collections/time-series.txt new file mode 100644 index 00000000..9c21e2e3 --- /dev/null +++ b/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 ``.system.buckets`` namespace. For more information, + see :manual:`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 +`. 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..35b005e2 --- /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 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~