DOCSP-38130: Time series collections

docs/fundamentals/database-collection.txt → docs/database-collection.txt

@@ -17,6 +17,12 @@ Databases and Collections
    :depth: 2
    :class: singlecol
 
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Time Series </database-collection/time-series>
+
 Overview
 --------
 

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
+<laravel-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
+
+.. 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 <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 <laravel-time-series-addtl-info>` 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 </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 querying data, see the :ref:`laravel-query-builder` guide.
+
+To learn more about performing aggregation operations, see the :ref:`laravel-aggregation-builder`
+guide.

docs/includes/database-collection/time-series-migration.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\Schema;
+use MongoDB\Laravel\Schema\Blueprint;
+
+return new class extends Migration
+{
+    protected $connection = 'mongodb';
+
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $options = [
+            'timeseries' => [
+                'timeField' => 'timestamp',
+                'metaField' => 'location',
+                'granularity' => 'minutes',
+            ]
+        ];
+
+        Schema::create('precipitation', null, $options);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::drop('precipitation');
+    }
+};

docs/index.txt

@@ -19,6 +19,7 @@
    Fundamentals </fundamentals>
    Eloquent Models </eloquent-models>
    Query Builder </query-builder>
+   Databases & Collections </database-collection>
    User Authentication </user-authentication>
    Cache & Locks </cache>
    Queues </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
 -------------