Docs Menu
Docs Home
/ / /
PHP Library Manual
/

Time Series Collections

On this page

  • Overview
  • Create a Time Series Collection
  • Insert Time Series Data
  • Query Time Series Collections
  • Additional Information

In this guide, you can learn how to use the MongoDB PHP Library 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:

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

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, pass an options array to the MongoDB\Database::createCollection() method that sets the timeseries option. When setting this 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'.

This example creates the sept2023 time series collection in the precipitation database with the following configuration:

  • timeField is set to 'timestamp'

  • metaField is set to 'location'

  • granularity is set to 'minutes'

$db = $client->precipitation;
$options = [
'timeseries' => [
'timeField' => 'timestamp',
'metaField' => 'location',
'granularity' => 'minutes',
]
];
$db->createCollection('sept2023', $options);

To verify that you successfully created the time series collection, call the MongoDB\Database::listCollections() method on the database and print the results:

$cursor = $db->listCollections();
foreach ($cursor as $collectionInfo) {
print_r($collectionInfo) . PHP_EOL;
}
MongoDB\Model\CollectionInfo Object
(
[name] => sept2023
[type] => timeseries
[options] => Array
(
)
[info] => Array
(
)
)
MongoDB\Model\CollectionInfo Object
(
[name] => system.buckets.sept2023
[type] => collection
[options] => Array
(
)
[info] => Array
(
)
)

Note

MongoDB stores system data associated with time series collections in the <database>.system.buckets namespace. For more information, see database.system.buckets in the MongoDB Server manual.

You can insert data into a time series collection by using the MongoDB\Collection::insertOne() or MongoDB\Collection::insertMany() methods and specifying the measurement, timestamp, and metadata in each inserted document.

Tip

To learn more about inserting documents into a collection, see the Insert Documents guide.

This example inserts New York City precipitation data into the sept2023 time series collection created in the Create a Time Series Collection 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

$collection = $db->sept2023;
$result = $collection->insertMany(
[
[
'precipitation_mm' => 0.5,
'location' => 'New York City',
'timestamp' => new MongoDB\BSON\UTCDateTime(1694829060000),
],
[
'precipitation_mm' => 2.8,
'location' => 'New York City',
'timestamp' => new MongoDB\BSON\UTCDateTime(1695594780000),
],
]
);

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 Additional Information section.

To learn more about the concepts mentioned in this guide, see the following Server manual entries:

To learn more about performing read operations, see Read Data from MongoDB.

To learn more about performing aggregation operations, see the Transform Your Data with Aggregation guide.

To learn more about the methods mentioned in this guide, see the following API documentation:

Back

Databases and Collections