Skip to content

Commit 5812fdf

Browse files
norareidynorareidy
authored
DOCSP-41964: Time series collections (#138)
* DOCSP-41964: Time series collections * toc * edits * keywords * SA feedback * JT feedback
1 parent 9ad7615 commit 5812fdf

File tree

4 files changed

+268
-3
lines changed

4 files changed

+268
-3
lines changed

‎source/databases-collections.txt

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ Databases and Collections
1717
.. meta::
1818
:keywords: table, row, organize, storage, code example
1919

20+
.. toctree::
21+
:titlesonly:
22+
:maxdepth: 1
23+
24+
/databases-collections/time-series
25+
2026
Overview
2127
--------
2228

@@ -319,4 +325,4 @@ guide, see the following API documentation:
319325
- :phpmethod:`MongoDB\Database::selectCollection()`
320326
- :phpmethod:`MongoDB\Database::createCollection()`
321327
- :phpmethod:`MongoDB\Database::listCollections()`
322-
- :phpmethod:`MongoDB\Database::dropCollection()`
328+
- :phpmethod:`MongoDB\Database::dropCollection()`

‎source/databases-collections/time-series.txt

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. _php-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 {+php-library+} 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+
.. _php-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 {+mdb-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, pass an options array to the
67+
``MongoDB\Database::createCollection()`` method that sets the
68+
``timeseries`` option. When setting this option, include the following fields:
69+
70+
- ``timeField``: Specifies the field that stores a timestamp in each time series document.
71+
- ``metaField``: Specifies the field that stores metadata in each time series document.
72+
- ``granularity``: Specifies the approximate time between consecutive timestamps. The possible
73+
values are ``'seconds'``, ``'minutes'``, and ``'hours'``.
74+
75+
.. _php-time-series-create-example:
76+
77+
Example
78+
~~~~~~~
79+
80+
This example creates the ``sept2023`` time series collection in the
81+
``precipitation`` database with the following configuration:
82+
83+
- ``timeField`` is set to ``'timestamp'``
84+
- ``metaField`` is set to ``'location'``
85+
- ``granularity`` is set to ``'minutes'``
86+
87+
.. literalinclude:: /includes/databases-collections/time-series.php
88+
:start-after: start-create-ts
89+
:end-before: end-create-ts
90+
:language: php
91+
:dedent:
92+
93+
To verify that you successfully created the time series collection, call
94+
the ``MongoDB\Database::listCollections()`` method on the database and
95+
print the results:
96+
97+
.. io-code-block::
98+
:copyable:
99+
100+
.. input:: /includes/databases-collections/time-series.php
101+
:start-after: start-list-colls
102+
:end-before: end-list-colls
103+
:language: php
104+
:dedent:
105+
106+
.. output::
107+
:language: console
108+
:visible: false
109+
110+
MongoDB\Model\CollectionInfo Object
111+
(
112+
[name] => sept2023
113+
[type] => timeseries
114+
[options] => Array
115+
(
116+
…
117+
)
118+
119+
[info] => Array
120+
(
121+
…
122+
)
123+
)
124+
MongoDB\Model\CollectionInfo Object
125+
(
126+
[name] => system.buckets.sept2023
127+
[type] => collection
128+
[options] => Array
129+
(
130+
…
131+
)
132+
133+
[info] => Array
134+
(
135+
…
136+
)
137+
)
138+
139+
.. note::
140+
141+
MongoDB stores system data associated with time series collections
142+
in the ``<database>.system.buckets`` namespace. For more information,
143+
see :manual:`database.system.buckets </reference/system-collections/#mongodb-data--database-.system.buckets>`
144+
in the {+mdb-server+} manual.
145+
146+
.. _php-time-series-insert:
147+
148+
Insert Time Series Data
149+
-----------------------
150+
151+
You can insert data into a time series collection by using the ``MongoDB\Collection::insertOne()``
152+
or ``MongoDB\Collection::insertMany()`` methods and specifying the measurement,
153+
timestamp, and metadata in each inserted document.
154+
155+
.. tip::
156+
157+
To learn more about inserting documents into a collection, see the :ref:`php-write-insert`
158+
guide.
159+
160+
Example
161+
~~~~~~~
162+
163+
This example inserts New York City precipitation data into the ``sept2023``
164+
time series collection created in the :ref:`Create a Time Series Collection example
165+
<php-time-series-create-example>`. Each document contains the following fields:
166+
167+
- ``precipitation_mm``, which stores precipitation measurements in millimeters
168+
- ``location``, which stores location metadata
169+
- ``timestamp``, which stores the time of the measurement collection
170+
171+
.. literalinclude:: /includes/databases-collections/time-series.php
172+
:start-after: start-insert-ts
173+
:end-before: end-insert-ts
174+
:language: php
175+
:dedent:
176+
177+
.. _php-time-series-query:
178+
179+
Query Time Series Collections
180+
-----------------------------
181+
182+
You can use the same syntax and conventions to query data stored in a time
183+
series collection as you use when performing read or aggregation operations on
184+
other collections. To find more information about these operations, see
185+
the :ref:`Additional Information <php-time-series-addtl-info>` section.
186+
187+
.. _php-time-series-addtl-info:
188+
189+
Additional Information
190+
----------------------
191+
192+
To learn more about the concepts mentioned in this guide, see the
193+
following Server manual entries:
194+
195+
- :manual:`Time Series </core/timeseries-collections/>`
196+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
197+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
198+
199+
To learn more about performing read operations, see :ref:`php-read`.
200+
201+
To learn more about performing aggregation operations, see the :ref:`php-aggregation`
202+
guide.
203+
204+
API Documentation
205+
~~~~~~~~~~~~~~~~~
206+
207+
To learn more about the methods mentioned in this guide, see the following
208+
API documentation:
209+
210+
- :phpmethod:`MongoDB\Database::createCollection()`
211+
- :phpmethod:`MongoDB\Database::listCollections()`
212+
- :phpmethod:`MongoDB\Collection::insertOne()`
213+
- :phpmethod:`MongoDB\Collection::insertMany()`

‎source/includes/databases-collections/time-series.php

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<?php
2+
require 'vendor/autoload.php';
3+
4+
$uri = getenv('MONGODB_URI') ?: 'mongodb://localhost:27017';
5+
$client = new MongoDB\Client($uri);
6+
7+
// Creates a time series collection to store precipitation data
8+
// start-create-ts
9+
$db = $client->precipitation;
10+
11+
$options = [
12+
'timeseries' => [
13+
'timeField' => 'timestamp',
14+
'metaField' => 'location',
15+
'granularity' => 'minutes',
16+
]
17+
];
18+
19+
$collection = $db->createCollection('sept2023', $options);
20+
// end-create-ts
21+
22+
// Lists the collections in the "precipitation" database
23+
// start-list-colls
24+
$cursor = $db->listCollections();
25+
26+
foreach ($cursor as $collectionInfo) {
27+
print_r($collectionInfo) . PHP_EOL;
28+
}
29+
// end-list-colls
30+
31+
// Inserts precipitation time series data about New York City into the collection
32+
// start-insert-ts
33+
$collection = $db->sept2023;
34+
$result = $collection->insertMany(
35+
[
36+
[
37+
'precipitation_mm' => 0.5,
38+
'location' => 'New York City',
39+
'timestamp' => new MongoDB\BSON\UTCDateTime(1694829060000),
40+
],
41+
[
42+
'precipitation_mm' => 2.8,
43+
'location' => 'New York City',
44+
'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000),
45+
],
46+
]
47+
);
48+
// end-insert-ts

‎source/tutorial/crud.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -414,8 +414,6 @@ following example finds restaurants whose name starts with "(Library)":
414414
'name' => new MongoDB\BSON\Regex('^' . preg_quote('(Library)')),
415415
]);
416416

417-
.. _php-aggregation:
418-
419417
Complex Queries with Aggregation
420418
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
421419

0 commit comments

Comments
 (0)