Skip to content

Commit 523c579

Browse files
norareidynorareidy
committed
DOCSP-41964: Time series collections
1 parent 55a44c1 commit 523c579

File tree

3 files changed

+267
-0
lines changed

3 files changed

+267
-0
lines changed

‎source/databases-collections.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _php-databases-collections:
2+
3+
=========================
4+
Databases and Collections
5+
=========================
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
/databases-collections/time-series

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

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
.. _php-time-series:
2+
3+
================
4+
Time Series Data
5+
================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
In this guide, you can learn how to use the {+php-library+} to create
19+
and interact with **time series collections**. These collections store
20+
time series data, which is composed of the following components:
21+
22+
- Measured quantity
23+
- Timestamp for the measurement
24+
- Metadata that describes the measurement
25+
26+
The following table describes sample situations for which you could store time
27+
series data:
28+
29+
.. list-table::
30+
:widths: 33, 33, 33
31+
:header-rows: 1
32+
:stub-columns: 1
33+
34+
* - Situation
35+
- Measured Quantity
36+
- Metadata
37+
38+
* - Recording monthly sales by industry
39+
- Revenue in USD
40+
- Company, country
41+
42+
* - Tracking weather changes
43+
- Precipitation level
44+
- Location, sensor type
45+
46+
* - Recording fluctuations in housing prices
47+
- Monthly rent price
48+
- Location, currency
49+
50+
.. _php-time-series-create:
51+
52+
Create a Time Series Collection
53+
-------------------------------
54+
55+
.. important:: Server Version for Time Series Collections
56+
57+
To create and interact with time series collections, you must be
58+
connected to a deployment running {+mdb-server+} 5.0 or later.
59+
60+
You can create a time series collection to store time series data.
61+
To create a time series collection, pass an options array to the
62+
``MongoDB\Database::createCollection()`` method that sets the
63+
``timeseries`` option. When setting this option, specify the following fields:
64+
65+
- ``timeField``: The field that stores a timestamp in each time series document.
66+
- ``metaField``: The field that stores metadata in each time series document.
67+
- ``granularity``: The approximate time between consecutive timestamps. The possible
68+
values are ``'seconds'``, ``'minutes'``, and ``'hours'``.
69+
70+
.. _php-time-series-create-example:
71+
72+
Example
73+
~~~~~~~
74+
75+
This example creates the ``sept2023`` time series collection in the
76+
``precipitation`` database with the following configuration:
77+
78+
- ``timeField`` is set to ``'timestamp'``
79+
- ``metaField`` is set to ``'location'``
80+
- ``granularity`` is set to ``'minutes'``
81+
82+
.. literalinclude:: /includes/databases-collections/time-series.php
83+
:start-after: start-create-ts
84+
:end-before: end-create-ts
85+
:language: php
86+
:dedent:
87+
88+
To verify that you successfully created the time series collection, call
89+
the ``MongoDB\Database::listCollections()`` method on the database and
90+
print the results:
91+
92+
.. io-code-block::
93+
:copyable:
94+
95+
.. input:: /includes/databases-collections/time-series.php
96+
:start-after: start-list-colls
97+
:end-before: end-list-colls
98+
:language: php
99+
:dedent:
100+
101+
.. output::
102+
:language: console
103+
:visible: false
104+
105+
MongoDB\Model\CollectionInfo Object
106+
(
107+
[name] => sept2023
108+
[type] => timeseries
109+
[options] => Array
110+
(
111+
…
112+
)
113+
114+
[info] => Array
115+
(
116+
…
117+
)
118+
)
119+
MongoDB\Model\CollectionInfo Object
120+
(
121+
[name] => system.buckets.sept2023
122+
[type] => collection
123+
[options] => Array
124+
(
125+
…
126+
)
127+
128+
[info] => Array
129+
(
130+
…
131+
)
132+
)
133+
134+
.. note::
135+
136+
MongoDB stores system data associated with time series collections
137+
in the ``<database>.system.buckets`` namespace. For more information,
138+
see :manual:`<database>.system.buckets </reference/system-collections/#mongodb-data--database-.system.buckets>`
139+
in the {+mdb-server+} manual.
140+
141+
.. _php-time-series-insert:
142+
143+
Insert Time Series Data
144+
-----------------------
145+
146+
You can insert data into a time series collection by using the ``MongoDB\Collection::insertOne()``
147+
or ``MongoDB\Collection::insertMany()`` methods and specifying the measurement,
148+
timestamp, and metadata in each inserted document.
149+
150+
.. tip::
151+
152+
To learn more about inserting documents into a collection, see the :ref:`php-write-insert`
153+
guide.
154+
155+
Example
156+
~~~~~~~
157+
158+
This example inserts New York City precipitation data into the ``sept2023``
159+
time series collection created in the :ref:`Create a Time Series Collection example
160+
<php-time-series-create-example>`. Each document contains the following fields:
161+
162+
- ``precipitation_mm``, which stores precipitation measurements in millimeters
163+
- ``location``, which stores location metadata
164+
- ``timestamp``, which stores the time of the measurement collection
165+
166+
.. literalinclude:: /includes/databases-collections/time-series.php
167+
:start-after: start-insert-ts
168+
:end-before: end-insert-ts
169+
:language: php
170+
:dedent:
171+
172+
.. _php-time-series-query:
173+
174+
Query Time Series Collections
175+
-----------------------------
176+
177+
You can use the same syntax and conventions to query data stored in a time
178+
series collection as you use when performing read or aggregation operations on
179+
other collections. To find more information about these operations, see
180+
the :ref:`Additional Information <php-time-series-addtl-info>` section.
181+
182+
.. _php-time-series-addtl-info:
183+
184+
Additional Information
185+
----------------------
186+
187+
To learn more about the concepts mentioned in this guide, see the
188+
following Server manual entries:
189+
190+
- :manual:`Time Series </core/timeseries-collections/>`
191+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
192+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
193+
194+
To learn more about performing read operations, see :ref:`php-read`.
195+
196+
To learn more about performing aggregation operations, see the :ref:`php-aggregation`
197+
guide.
198+
199+
API Documentation
200+
~~~~~~~~~~~~~~~~~
201+
202+
To learn more about the methods mentioned in this guide, see the following
203+
API documentation:
204+
205+
- :phpmethod:`MongoDB\Database::createCollection()`
206+
- :phpmethod:`MongoDB\Database::listCollections()`
207+
- :phpmethod:`MongoDB\Collection::insertOne()`
208+
- :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') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset');
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

0 commit comments

Comments
 (0)