Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 37a7710

Browse files
Merge 5.1 into 5.x (#3284)
2 parents cb3b32c + f62046d commit 37a7710

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

Lines changed: 6 additions & 0 deletions
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

Lines changed: 174 additions & 0 deletions
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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ 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>
@@ -26,7 +25,6 @@ Fundamentals
2625
Learn more about the following concepts related to {+odm-long+}:
2726

2827
- :ref:`laravel-fundamentals-connection`
29-
- :ref:`laravel-db-coll`
3028
- :ref:`laravel-fundamentals-read-ops`
3129
- :ref:`laravel-fundamentals-write-ops`
3230
- :ref:`laravel-aggregation-builder`
Lines changed: 35 additions & 0 deletions
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

Lines changed: 24 additions & 0 deletions
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\Driver\ReadPreference;
1516
use MongoDB\Laravel\Tests\TestCase;
@@ -678,4 +679,27 @@ public function testUnset(): void
678679

679680
$this->assertIsInt($result);
680681
}
682+
683+
public function testTimeSeries(): void
684+
{
685+
// begin time series
686+
$data = [
687+
[
688+
'precipitation_mm' => 0.5,
689+
'location' => 'New York City',
690+
'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')),
691+
],
692+
[
693+
'precipitation_mm' => 2.8,
694+
'location' => 'New York City',
695+
'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')),
696+
],
697+
];
698+
699+
$result = DB::table('precipitation')
700+
->insert($data);
701+
// end time series
702+
703+
$this->assertTrue($result);
704+
}
681705
}

‎docs/index.txt

Lines changed: 7 additions & 0 deletions
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
HTTP Sessions </sessions>
@@ -90,6 +91,12 @@ see the following content:
9091
- :ref:`laravel-transactions`
9192
- :ref:`laravel-filesystems`
9293

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

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /