Skip to content

Commit f62046d

Browse files
norareidynorareidy
authored
DOCSP-38130: Time series collections (#3274)
* DOCSP-38130: Time sereies collections * apply phpcbf formatting * fix * build error * JT feedback * apply phpcbf formatting * fixes * apply phpcbf formatting * JT feedback 2
1 parent 152fc55 commit f62046d

File tree

6 files changed

+246
-2
lines changed

6 files changed

+246
-2
lines changed

‎docs/fundamentals/database-collection.txt renamed to ‎docs/database-collection.txt

+6
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ Databases and Collections
1717
:depth: 2
1818
:class: singlecol
1919

20+
.. toctree::
21+
:titlesonly:
22+
:maxdepth: 1
23+
24+
Time Series </database-collection/time-series>
25+
2026
Overview
2127
--------
2228

‎docs/database-collection/time-series.txt

+174
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.. _laravel-time-series:
2+
3+
=======================
4+
Time Series Collections
5+
=======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: chronological, data format, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+odm-short+} to create
24+
and interact with **time series collections**. These collections store
25+
time series data, which is composed of the following components:
26+
27+
- Measured quantity
28+
- Timestamp for the measurement
29+
- Metadata that describes the measurement
30+
31+
The following table describes sample situations for which you can store time
32+
series data:
33+
34+
.. list-table::
35+
:widths: 33, 33, 33
36+
:header-rows: 1
37+
:stub-columns: 1
38+
39+
* - Situation
40+
- Measured Quantity
41+
- Metadata
42+
43+
* - Recording monthly sales by industry
44+
- Revenue in USD
45+
- Company, country
46+
47+
* - Tracking weather changes
48+
- Precipitation level
49+
- Location, sensor type
50+
51+
* - Recording fluctuations in housing prices
52+
- Monthly rent price
53+
- Location, currency
54+
55+
.. _laravel-time-series-create:
56+
57+
Create a Time Series Collection
58+
-------------------------------
59+
60+
.. important:: Server Version for Time Series Collections
61+
62+
To create and interact with time series collections, you must be
63+
connected to a deployment running MongoDB Server 5.0 or later.
64+
65+
You can create a time series collection to store time series data.
66+
To create a time series collection, create a migration class and
67+
add an ``up()`` function to specify the collection configuration.
68+
In the ``up()`` function, pass the new collection's name
69+
and the ``timeseries`` option to the ``Schema::create()`` method.
70+
71+
.. tip::
72+
73+
To learn more about creating a migration class, see :ref:`laravel-eloquent-migrations`
74+
in the Schema Builder guide.
75+
76+
When setting the ``timeseries`` option, include the following fields:
77+
78+
- ``timeField``: Specifies the field that stores a timestamp in each time series document.
79+
- ``metaField``: Specifies the field that stores metadata in each time series document.
80+
- ``granularity``: Specifies the approximate time between consecutive timestamps. The possible
81+
values are ``'seconds'``, ``'minutes'``, and ``'hours'``.
82+
83+
.. _laravel-time-series-create-example:
84+
85+
Example
86+
~~~~~~~
87+
88+
This example migration class creates the ``precipitation`` time series collection
89+
with the following configuration:
90+
91+
- ``timeField`` is set to ``'timestamp'``
92+
- ``metaField`` is set to ``'location'``
93+
- ``granularity`` is set to ``'minutes'``
94+
95+
.. literalinclude:: /includes/database-collection/time-series-migration.php
96+
:language: php
97+
:dedent:
98+
99+
To verify that you successfully created the time series collection, call
100+
the ``Schema::hasCollection()`` method and pass the collection name as
101+
a parameter:
102+
103+
.. code-block:: php
104+
105+
$result = Schema::hasCollection('precipitation');
106+
echo $result;
107+
108+
If the collection exists, the ``hasCollection()`` method returns a
109+
value of ``true``.
110+
111+
.. _laravel-time-series-insert:
112+
113+
Insert Time Series Data
114+
-----------------------
115+
116+
You can insert data into a time series collection by passing your documents to the ``insert()``
117+
method and specifying the measurement, timestamp, and metadata in each inserted document.
118+
119+
.. tip::
120+
121+
To learn more about inserting documents into a collection, see :ref:`laravel-fundamentals-insert-documents`
122+
in the Write Operations guide.
123+
124+
Example
125+
~~~~~~~
126+
127+
This example inserts New York City precipitation data into the ``precipitation``
128+
time series collection created in the :ref:`Create a Time Series Collection example
129+
<laravel-time-series-create-example>`. Each document contains the following fields:
130+
131+
- ``precipitation_mm``, which stores precipitation measurements in millimeters
132+
- ``location``, which stores location metadata
133+
- ``timestamp``, which stores the time of the measurement collection
134+
135+
.. literalinclude:: /includes/query-builder/QueryBuilderTest.php
136+
:language: php
137+
:dedent:
138+
:start-after: begin time series
139+
:end-before: end time series
140+
141+
.. note::
142+
143+
The preceding example uses the :ref:`Laravel query builder <laravel-query-builder>`
144+
to insert documents into the time series collection. Alternatively,
145+
you can create an Eloquent model that represents the collection and
146+
perform insert operations on your model. To learn more, see
147+
the :ref:`laravel-eloquent-model-class` guide.
148+
149+
.. _laravel-time-series-query:
150+
151+
Query Time Series Collections
152+
-----------------------------
153+
154+
You can use the same syntax and conventions to query data stored in a time
155+
series collection as you use when performing read or aggregation operations on
156+
other collections. To find more information about these operations, see
157+
the :ref:`Additional Information <laravel-time-series-addtl-info>` section.
158+
159+
.. _laravel-time-series-addtl-info:
160+
161+
Additional Information
162+
----------------------
163+
164+
To learn more about the concepts mentioned in this guide, see the
165+
following MongoDB {+server-docs-name+} entries:
166+
167+
- :manual:`Time Series </core/timeseries-collections/>`
168+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
169+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
170+
171+
To learn more about querying data, see the :ref:`laravel-query-builder` guide.
172+
173+
To learn more about performing aggregation operations, see the :ref:`laravel-aggregation-builder`
174+
guide.

‎docs/fundamentals.txt

-2
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,13 @@ Fundamentals
1616
:maxdepth: 1
1717

1818
Connections </fundamentals/connection>
19-
Databases & Collections </fundamentals/database-collection>
2019
Read Operations </fundamentals/read-operations>
2120
Write Operations </fundamentals/write-operations>
2221
Aggregation Builder </fundamentals/aggregation-builder>
2322

2423
Learn more about the following concepts related to {+odm-long+}:
2524

2625
- :ref:`laravel-fundamentals-connection`
27-
- :ref:`laravel-db-coll`
2826
- :ref:`laravel-fundamentals-read-ops`
2927
- :ref:`laravel-fundamentals-write-ops`
3028
- :ref:`laravel-aggregation-builder`

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

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use Illuminate\Database\Migrations\Migration;
6+
use Illuminate\Support\Facades\Schema;
7+
8+
return new class extends Migration
9+
{
10+
protected $connection = 'mongodb';
11+
12+
/**
13+
* Run the migrations.
14+
*/
15+
public function up(): void
16+
{
17+
$options = [
18+
'timeseries' => [
19+
'timeField' => 'timestamp',
20+
'metaField' => 'location',
21+
'granularity' => 'minutes',
22+
],
23+
];
24+
25+
Schema::create('precipitation', null, $options);
26+
}
27+
28+
/**
29+
* Reverse the migrations.
30+
*/
31+
public function down(): void
32+
{
33+
Schema::drop('precipitation');
34+
}
35+
};

‎docs/includes/query-builder/QueryBuilderTest.php

+24
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
use Illuminate\Support\Facades\DB;
1111
use MongoDB\BSON\ObjectId;
1212
use MongoDB\BSON\Regex;
13+
use MongoDB\BSON\UTCDateTime;
1314
use MongoDB\Collection;
1415
use MongoDB\Laravel\Tests\TestCase;
1516

@@ -665,4 +666,27 @@ public function testUnset(): void
665666

666667
$this->assertIsInt($result);
667668
}
669+
670+
public function testTimeSeries(): void
671+
{
672+
// begin time series
673+
$data = [
674+
[
675+
'precipitation_mm' => 0.5,
676+
'location' => 'New York City',
677+
'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')),
678+
],
679+
[
680+
'precipitation_mm' => 2.8,
681+
'location' => 'New York City',
682+
'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')),
683+
],
684+
];
685+
686+
$result = DB::table('precipitation')
687+
->insert($data);
688+
// end time series
689+
690+
$this->assertTrue($result);
691+
}
668692
}

‎docs/index.txt

+7
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
Fundamentals </fundamentals>
2020
Eloquent Models </eloquent-models>
2121
Query Builder </query-builder>
22+
Databases & Collections </database-collection>
2223
User Authentication </user-authentication>
2324
Cache & Locks </cache>
2425
Queues </queues>
@@ -88,6 +89,12 @@ see the following content:
8889
- :ref:`laravel-transactions`
8990
- :ref:`laravel-filesystems`
9091

92+
Databases and Collections
93+
-------------------------
94+
95+
Learn how to use the {+odm-short+} to work with MongoDB databases and collections
96+
in the :ref:`laravel-db-coll` section.
97+
9198
Issues & Help
9299
-------------
93100

0 commit comments

Comments
 (0)