Time Series Collections

On this page

Overview

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

Overview

In this guide, you can learn how to use the Laravel Integration 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

Create a Time Series Collection

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, create a migration class and add an up() function to specify the collection configuration. In the up() function, pass the new collection's name and the timeseries option to the Schema::create() method.

Tip

To learn more about creating a migration class, see Perform Laravel Migrations in the Schema Builder guide.

When setting the timeseries 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'.

Example

This example migration class creates the precipitation time series collection with the following configuration:

timeField is set to 'timestamp'
metaField is set to 'location'
granularity is set to 'minutes'

<?php
declare(strict_types=1);
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
    protected $connection = 'mongodb';
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        $options = [
            'timeseries' => [
                'timeField' => 'timestamp',
                'metaField' => 'location',
                'granularity' => 'minutes',
            ],
        ];
        Schema::create('precipitation', null, $options);
    }
    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::drop('precipitation');
    }
};

To verify that you successfully created the time series collection, call the Schema::hasCollection() method and pass the collection name as a parameter:

$result = Schema::hasCollection('precipitation');
echo $result;

If the collection exists, the hasCollection() method returns a value of true.

Insert Time Series Data

You can insert data into a time series collection by passing your documents to the insert() method and specifying the measurement, timestamp, and metadata in each inserted document.

Tip

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

Example

This example inserts New York City precipitation data into the precipitation 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

$data = [
    [
        'precipitation_mm' => 0.5,
        'location' => 'New York City',
        'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 12, 0, 0, 0, 'CET')),
    ],
    [
        'precipitation_mm' => 2.8,
        'location' => 'New York City',
        'timestamp' => new UTCDateTime(Carbon::create(2023, 9, 17, 0, 0, 0, 'CET')),
    ],
];
$result = DB::table('precipitation')
    ->insert($data);

Note

The preceding example uses the Laravel query builder to insert documents into the time series collection. Alternatively, you can create an Eloquent model that represents the collection and perform insert operations on your model. To learn more, see the Eloquent Model Class guide.

Query Time Series Collections

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.

Additional Information

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

To learn more about querying data, see the Query Builder guide.

To learn more about performing aggregation operations, see the Aggregation Builder guide.

Back

Databases & Collections

User Authentication