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..cfd17828d --- /dev/null +++ b/docs/database-collection/time-series.txt @@ -0,0 +1,174 @@ +.. _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('precipitation'); + echo $result; + +If the collection exists, the ``hasCollection()`` method returns a +value of ``true``. + +.. _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 + +.. literalinclude:: /includes/query-builder/QueryBuilderTest.php + :language: php + :dedent: + :start-after: begin time series + :end-before: end time series + +.. 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/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` 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..2ea817822 --- /dev/null +++ b/docs/includes/database-collection/time-series-migration.php @@ -0,0 +1,35 @@ + [ + 'timeField' => 'timestamp', + 'metaField' => 'location', + 'granularity' => 'minutes', + ], + ]; + + Schema::create('precipitation', null, $options); + } + + /** + * Reverse the migrations. + */ + public function down(): void + { + Schema::drop('precipitation'); + } +}; diff --git a/docs/includes/query-builder/QueryBuilderTest.php b/docs/includes/query-builder/QueryBuilderTest.php index d99796fb2..884c54b5f 100644 --- a/docs/includes/query-builder/QueryBuilderTest.php +++ b/docs/includes/query-builder/QueryBuilderTest.php @@ -10,6 +10,7 @@ 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; @@ -665,4 +666,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->assertTrue($result); + } } 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 -------------