Docs Menu
Docs Home
/
MongoDB Manual
/
Time Series

Time Series Quick Start

On this page

  • Steps
  • Sample Data
  • Learning Summary
  • Next Steps
  • Learn More

This quick start describes how to configure, create, and query a time series collection with MongoDB Atlas or a self-managed deployment.

Time required: 30 minutes

Steps

1

Set up your Atlas cluster.

  1. Create a free Atlas account or sign in to an existing account.

  2. If you don't yet have an Atlas cluster, create a free M0 cluster. To learn more about creating an Atlas cluster, see Create a Cluster.

    Note

    If you are working with an existing cluster, you must have Project Data Access Admin or higher access to your Atlas project.

    If you create a new cluster, you have the necessary permissions by default.

    You can create only one M0 Free cluster per project.

  3. In the left sidebar, click Overview. Choose your cluster and click Connect.

  4. Under Access your data through tools, click Shell.

    If you haven't already, follow the steps provided to download and install mongosh.

  5. Copy your connection string and click Done.

2

Open a new terminal window and connect to your deployment.

Use mongosh to connect to your self-managed or Atlas deployment. For example:

mongosh "mongodb+srv://my-test-cluster.1twap.mongodb.net/" --apiVersion 1
--username <user>
3

Create a new database.

use timeseries

This creates and switches to an empty "timeseries" database.

4

Create an empty time series collection.

Note

This exercise uses stock ticker sample data. The date field stores time data, and the ticker field identifies the individual stock.

  1. Set the timeField, metaField, and granularity:

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds"
    }

    OR specify custom granularity:

    New in version 6.3.

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds",
       bucketMaxSpanSeconds: "300",
       bucketRoundingSeconds: "300"
    }

  2. Create the collection using the db.createCollection() method:

    db.createCollection(
       "stocks",
       {
          timeseries: {
             timeField: "date",
             metaField: "ticker",
             granularity: "seconds"
          }
       })

    This creates an empty time series collection named stocks.

5

Add sample documents.

Run the db.collection.insertMany() method to add the following sample documents to the collection:

db.stocks.insertMany([
   { ticker: "MDB", date: ISODate("2021-12-18T15:59:00.000Z"), close: 252.47, volume: 55046.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:58:00.000Z"), close: 252.93, volume: 44042.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:57:00.000Z"), close: 253.61, volume: 40182.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:56:00.000Z"), close: 253.63, volume: 27890.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:55:00.000Z"), close: 254.03, volume: 40270.00}
])

If you are running MongoDB on Atlas, you can click Browse collections to view the sample data.

6

Query the data.

You query a time series collection like any other MongoDB collection. For more information, see About Querying Time Series Data.

Common queries for time series data are querying the metaField to get data for a single time series, or using a range query on the timeField to get data for a given time span.

To query the metaField for a single time series:

db.stocks.find( { ticker: "MDB" } )

To query the timeField for a time span:

db.stocks.find({ date : {
   $gte : ISODate("2021-12-18T15:50:00.000Z"),
   $lte : ISODate("2021-12-18T15:56:00.000Z")}
});
1

Install the dependencies.

For detailed instructions, see Prerequisites.

  1. Install the Atlas CLI.

    If you use Homebrew, you can run the following command in your terminal:

    brew install mongodb-atlas-cli

    For installation instructions on other operating systems, see Install the Atlas CLI

  2. Install Docker.

    Docker requires a network connection for pulling and caching MongoDB images.

2

Set up your local Atlas deployment.

  1. If you don't have an existing Atlas account, run atlas setup in your terminal or create a new account.

  2. Run atlas deployments setup and follow the prompts to create a local deployment. When prompted to connect to the deployment, select skip.

    For detailed instructions, see Create a Local Atlas Deployment.

3

Install mongosh.

4

Open a new terminal window and connect to your deployment.

Use mongosh to connect to your self-managed or Atlas deployment. For example:

mongosh "mongodb+srv://my-test-cluster.1twap.mongodb.net/" --apiVersion 1
--username <user>
5

Create a new database.

use timeseries

This creates and switches to an empty "timeseries" database.

6

Create an empty time series collection.

Note

This exercise uses stock ticker sample data. The date field stores time data, and the ticker field identifies the individual stock.

  1. Set the timeField, metaField, and granularity:

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds"
    }

    OR specify custom granularity:

    New in version 6.3.

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds",
       bucketMaxSpanSeconds: "300",
       bucketRoundingSeconds: "300"
    }

  2. Create the collection using the db.createCollection() method:

    db.createCollection(
       "stocks",
       {
          timeseries: {
             timeField: "date",
             metaField: "ticker",
             granularity: "seconds"
          }
       })

    This creates an empty time series collection named stocks.

7

Add sample documents.

Run the db.collection.insertMany() method to add the following sample documents to the collection:

db.stocks.insertMany([
   { ticker: "MDB", date: ISODate("2021-12-18T15:59:00.000Z"), close: 252.47, volume: 55046.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:58:00.000Z"), close: 252.93, volume: 44042.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:57:00.000Z"), close: 253.61, volume: 40182.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:56:00.000Z"), close: 253.63, volume: 27890.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:55:00.000Z"), close: 254.03, volume: 40270.00}
])

If you are running MongoDB on Atlas, you can click Browse collections to view the sample data.

8

Query the data.

You query a time series collection like any other MongoDB collection. For more information, see About Querying Time Series Data.

Common queries for time series data are querying the metaField to get data for a single time series, or using a range query on the timeField to get data for a given time span.

To query the metaField for a single time series:

db.stocks.find( { ticker: "MDB" } )

To query the timeField for a time span:

db.stocks.find({ date : {
   $gte : ISODate("2021-12-18T15:50:00.000Z"),
   $lte : ISODate("2021-12-18T15:56:00.000Z")}
});
1

Install MongoDB and dependencies.

If you're running a self-managed deployment, follow the installation instructions for your MongoDB version, edition, and platform.

2

Install mongosh.

3

Open a new terminal window and connect to your deployment.

Use mongosh to connect to your self-managed or Atlas deployment. For example:

mongosh "mongodb+srv://my-test-cluster.1twap.mongodb.net/" --apiVersion 1
--username <user>
4

Create a new database.

use timeseries

This creates and switches to an empty "timeseries" database.

5

Create an empty time series collection.

Note

This exercise uses stock ticker sample data. The date field stores time data, and the ticker field identifies the individual stock.

  1. Set the timeField, metaField, and granularity:

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds"
    }

    OR specify custom granularity:

    New in version 6.3.

    timeseries: {
       timeField: "date",
       metaField: "ticker",
       granularity: "seconds",
       bucketMaxSpanSeconds: "300",
       bucketRoundingSeconds: "300"
    }

  2. Create the collection using the db.createCollection() method:

    db.createCollection(
       "stocks",
       {
          timeseries: {
             timeField: "date",
             metaField: "ticker",
             granularity: "seconds"
          }
       })

    This creates an empty time series collection named stocks.

6

Add sample documents.

Run the db.collection.insertMany() method to add the following sample documents to the collection:

db.stocks.insertMany([
   { ticker: "MDB", date: ISODate("2021-12-18T15:59:00.000Z"), close: 252.47, volume: 55046.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:58:00.000Z"), close: 252.93, volume: 44042.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:57:00.000Z"), close: 253.61, volume: 40182.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:56:00.000Z"), close: 253.63, volume: 27890.00},
   { ticker: "MDB", date: ISODate("2021-12-18T15:55:00.000Z"), close: 254.03, volume: 40270.00}
])

If you are running MongoDB on Atlas, you can click Browse collections to view the sample data.

7

Query the data.

You query a time series collection like any other MongoDB collection. For more information, see About Querying Time Series Data.

Common queries for time series data are querying the metaField to get data for a single time series, or using a range query on the timeField to get data for a given time span.

To query the metaField for a single time series:

db.stocks.find( { ticker: "MDB" } )

To query the timeField for a time span:

db.stocks.find({ date : {
   $gte : ISODate("2021-12-18T15:50:00.000Z"),
   $lte : ISODate("2021-12-18T15:56:00.000Z")}
});

Sample Data

This quick start creates a stocks time series collection with the following document structure.

{
   _id: ObjectId(...),
   ticker: <string>,
   date: ISODate(...),
   close: <double>,
   volume: <double>
}

Learning Summary

This quick start focused on creating a new time series collection. Because time series collections are optimized for time data, their performance depends heavily on how you configure them at creation. For more information, see Time Series Collection Considerations.

Next Steps

Learn More

Back

Time Series

Next

Time Series Data