From afc751c7d204ae4ca26c1842ed9f3a23ea0894de Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 12 Feb 2025 14:36:30 -0500 Subject: [PATCH 1/9] DOCSP-38130: Time sereies collections --- .../database-collection.txt | 6 + docs/database-collection/time-series.txt | 186 ++++++++++++++++++ .../time-series-migration.php | 36 ++++ docs/index.txt | 7 + 4 files changed, 235 insertions(+) rename docs/{fundamentals => }/database-collection.txt (98%) create mode 100644 docs/database-collection/time-series.txt create mode 100644 docs/includes/database-collection/time-series-migration.php diff --git a/docs/fundamentals/database-collection.txt b/docs/database-collection.txt similarity index 98% rename from docs/fundamentals/database-collection.txt rename to docs/database-collection.txt index a453d81a9..fb6573147 100644 --- a/docs/fundamentals/database-collection.txt +++ b/docs/database-collection.txt @@ -17,6 +17,12 @@ Databases and Collections :depth: 2 :class: singlecol +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Time Series + Overview -------- diff --git a/docs/database-collection/time-series.txt b/docs/database-collection/time-series.txt new file mode 100644 index 000000000..1f208f611 --- /dev/null +++ b/docs/database-collection/time-series.txt @@ -0,0 +1,186 @@ +.. _laravel-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 {+odm-short+} 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 + +.. _laravel-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 MongoDB Server 5.0 or later. + +You can create a time series collection to store time series data. +To create a time series collection, create a migration class and +add an ``up()`` function to specify the collection configuration. +In the ``up()`` function, pass the new collection's name +and the ``timeseries`` option to the ``Schema::create()`` method. + +.. tip:: + + To learn more about creating a migration class, see :ref:`laravel-eloquent-migrations` + in the Schema Builder guide. + +When setting the ``timeseries`` 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'``. + +.. _laravel-time-series-create-example: + +Example +~~~~~~~ + +This example migration class creates the ``precipitation`` time series collection +with the following configuration: + +- ``timeField`` is set to ``'timestamp'`` +- ``metaField`` is set to ``'location'`` +- ``granularity`` is set to ``'minutes'`` + +.. literalinclude:: /includes/database-collection/time-series-migration.php + :language: php + :dedent: + +To verify that you successfully created the time series collection, call +the ``Schema::hasCollection()`` method and pass the collection name as +a parameter: + +.. code-block:: php + + $result = Schema::hasCollection('ts-collection'); + echo $result; + +The ``hasCollection()`` method returns a value of ``1`` if the +collection exists. + +.. _laravel-time-series-insert: + +Insert Time Series Data +----------------------- + +You can insert data into a time series collection by passing your documents to the ``insert()`` +method and specifying the measurement, timestamp, and metadata in each inserted document. + +.. tip:: + + To learn more about inserting documents into a collection, see :ref:`laravel-fundamentals-insert-documents` + in the Write Operations guide. + +Example +~~~~~~~ + +This example inserts New York City precipitation data into the ``precipitation`` +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 + +.. code-block:: php + + $data = [ + [ + 'precipitation_mm' => 0.5, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')), + ], + [ + 'precipitation_mm' => 2.8, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')), + ], + ]; + + $result = DB::table('precipitation') + ->insert($data); + +.. note:: + + The preceding example uses the :ref:`Laravel query builder ` + to insert documents into the time series collection. Alternatively, + you can create an Eloquent model that represents the collection and + perform insert operations on your model. To learn more, see + the :ref:`laravel-eloquent-model-class` guide. + +.. _laravel-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. + +.. _laravel-time-series-addtl-info: + +Additional Information +---------------------- + +To learn more about the concepts mentioned in this guide, see the +following MongoDB {+server-docs-name+} entries: + +- :manual:`Time Series ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +To learn more about querying data, see the :ref:`laravel-query-builder` guide. + +To learn more about performing aggregation operations, see the :ref:`laravel-aggregation-builder` +guide. diff --git a/docs/includes/database-collection/time-series-migration.php b/docs/includes/database-collection/time-series-migration.php new file mode 100644 index 000000000..e3beb24c1 --- /dev/null +++ b/docs/includes/database-collection/time-series-migration.php @@ -0,0 +1,36 @@ + [ + 'timeField' => 'timestamp', + 'metaField' => 'location', + 'granularity' => 'minutes', + ] + ]; + + Schema::create('precipitation', null, $options); + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('precipitation'); + } +}; \ No newline at end of file diff --git a/docs/index.txt b/docs/index.txt index 104a6aa77..6b91880f9 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -19,6 +19,7 @@ Fundamentals Eloquent Models Query Builder + Databases & Collections User Authentication Cache & Locks Queues @@ -88,6 +89,12 @@ see the following content: - :ref:`laravel-transactions` - :ref:`laravel-filesystems` +Databases and Collections +------------------------- + +Learn how to use the {+odm-short+} to work with MongoDB databases and collections +in the :ref:`laravel-db-coll` section. + Issues & Help ------------- From 55b2470f36ef08e6748ced5efff1d33e5caa0613 Mon Sep 17 00:00:00 2001 From: norareidy <107268623+norareidy@users.noreply.github.com> Date: Wed, 12 Feb 2025 19:37:20 +0000 Subject: [PATCH 2/9] apply phpcbf formatting --- docs/includes/database-collection/time-series-migration.php | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/includes/database-collection/time-series-migration.php b/docs/includes/database-collection/time-series-migration.php index e3beb24c1..2ea817822 100644 --- a/docs/includes/database-collection/time-series-migration.php +++ b/docs/includes/database-collection/time-series-migration.php @@ -4,7 +4,6 @@ use Illuminate\Database\Migrations\Migration; use Illuminate\Support\Facades\Schema; -use MongoDB\Laravel\Schema\Blueprint; return new class extends Migration { @@ -20,7 +19,7 @@ public function up(): void 'timeField' => 'timestamp', 'metaField' => 'location', 'granularity' => 'minutes', - ] + ], ]; Schema::create('precipitation', null, $options); @@ -33,4 +32,4 @@ public function down(): void { Schema::drop('precipitation'); } -}; \ No newline at end of file +}; From 79126ce970c3f9d83d3ae86548339816ac384c24 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 12 Feb 2025 14:49:17 -0500 Subject: [PATCH 3/9] fix --- docs/database-collection/time-series.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/database-collection/time-series.txt b/docs/database-collection/time-series.txt index 1f208f611..9746894c7 100644 --- a/docs/database-collection/time-series.txt +++ b/docs/database-collection/time-series.txt @@ -102,7 +102,7 @@ a parameter: .. code-block:: php - $result = Schema::hasCollection('ts-collection'); + $result = Schema::hasCollection('precipitation'); echo $result; The ``hasCollection()`` method returns a value of ``1`` if the From 4a50208fa8b33955e31c7a1ac9e9c9c01083ff7b Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 12 Feb 2025 15:01:08 -0500 Subject: [PATCH 4/9] build error --- docs/fundamentals.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/fundamentals.txt b/docs/fundamentals.txt index db482b2b8..fc67d4c48 100644 --- a/docs/fundamentals.txt +++ b/docs/fundamentals.txt @@ -16,7 +16,6 @@ Fundamentals :maxdepth: 1 Connections - Databases & Collections Read Operations Write Operations Aggregation Builder @@ -24,7 +23,6 @@ Fundamentals Learn more about the following concepts related to {+odm-long+}: - :ref:`laravel-fundamentals-connection` -- :ref:`laravel-db-coll` - :ref:`laravel-fundamentals-read-ops` - :ref:`laravel-fundamentals-write-ops` - :ref:`laravel-aggregation-builder` From 4e7eff5c1f8ef85e64a4da931570a6f889f53f5f Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 13:54:19 -0500 Subject: [PATCH 5/9] JT feedback --- docs/database-collection/time-series.txt | 26 +++++-------------- .../query-builder/QueryBuilderTest.php | 23 ++++++++++++++++ 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/docs/database-collection/time-series.txt b/docs/database-collection/time-series.txt index 9746894c7..8b30fbb1e 100644 --- a/docs/database-collection/time-series.txt +++ b/docs/database-collection/time-series.txt @@ -105,8 +105,8 @@ a parameter: $result = Schema::hasCollection('precipitation'); echo $result; -The ``hasCollection()`` method returns a value of ``1`` if the -collection exists. +If the collection exists, the ``hasCollection()`` method returns a +value of ``true``. .. _laravel-time-series-insert: @@ -132,23 +132,11 @@ time series collection created in the :ref:`Create a Time Series Collection exam - ``location``, which stores location metadata - ``timestamp``, which stores the time of the measurement collection -.. code-block:: php - - $data = [ - [ - 'precipitation_mm' => 0.5, - 'location' => 'New York City', - 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')), - ], - [ - 'precipitation_mm' => 2.8, - 'location' => 'New York City', - 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')), - ], - ]; - - $result = DB::table('precipitation') - ->insert($data); +.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php + :language: php + :dedent: + :start-after: begin time series + :end-before: end time series .. note:: diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..9c19afbe3 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -665,4 +665,27 @@ public function testUnset(): void $this->assertIsInt($result); } + + public function testTimeSeries(): void + { + // begin time series + $data = [ + [ + 'precipitation_mm' => 0.5, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')), + ], + [ + 'precipitation_mm' => 2.8, + 'location' => 'New York City', + 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')), + ], + ]; + + $result = DB::table('precipitation') + ->insert($data); + // end time series + + $this->assertIsBool($result); + } } From 38d929ceeb95d930f94c43863467c3f4c8839a0e Mon Sep 17 00:00:00 2001 From: norareidy <107268623+norareidy@users.noreply.github.com> Date: Fri, 21 Feb 2025 18:56:25 +0000 Subject: [PATCH 6/9] apply phpcbf formatting --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 9c19afbe3..fd253ee6e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -681,7 +681,7 @@ public function testTimeSeries(): void 'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')), ], ]; - + $result = DB::table('precipitation') ->insert($data); // end time series From bfb75114a2e0c73a86052cffa9491208e526d8f9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 14:15:32 -0500 Subject: [PATCH 7/9] fixes --- docs/database-collection/time-series.txt | 2 +- docs/includes/query-builder/QueryBuilderTest.php | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/database-collection/time-series.txt b/docs/database-collection/time-series.txt index 8b30fbb1e..cfd17828d 100644 --- a/docs/database-collection/time-series.txt +++ b/docs/database-collection/time-series.txt @@ -132,7 +132,7 @@ time series collection created in the :ref:`Create a Time Series Collection exam - ``location``, which stores location metadata - ``timestamp``, which stores the time of the measurement collection -.. literalinclude:: /includes/fundamentals/write-operations/WriteOperationsTest.php +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php :language: php :dedent: :start-after: begin time series diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 9c19afbe3..4f79448d2 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -5,6 +5,7 @@ namespace App\Http\Controllers; use Carbon\Carbon; +use MongoDB\BSON\UTCDateTime; use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; From 0e239b47bd3a0da4e61243b2e297ba0f069cf8d8 Mon Sep 17 00:00:00 2001 From: norareidy <107268623+norareidy@users.noreply.github.com> Date: Fri, 21 Feb 2025 19:16:50 +0000 Subject: [PATCH 8/9] apply phpcbf formatting --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 51c9f5e13..348fe262e 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -5,12 +5,12 @@ namespace App\Http\Controllers; use Carbon\Carbon; -use MongoDB\BSON\UTCDateTime; use Illuminate\Database\Query\Builder; use Illuminate\Pagination\AbstractPaginator; use Illuminate\Support\Facades\DB; use MongoDB\BSON\ObjectId; use MongoDB\BSON\Regex; +use MongoDB\BSON\UTCDateTime; use MongoDB\Collection; use MongoDB\Laravel\Tests\TestCase; From f03795759eb54f55fb041552310f52296482254a Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 21 Feb 2025 14:55:41 -0500 Subject: [PATCH 9/9] JT feedback 2 --- docs/includes/query-builder/QueryBuilderTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index 348fe262e..884c54b5f 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -687,6 +687,6 @@ public function testTimeSeries(): void ->insert($data); // end time series - $this->assertIsBool($result); + $this->assertTrue($result); } }