Docs Menu
Docs Home
/
Languages
/
Java
/
Java Reactive Streams Driver
/
Specialized Data Formats

Time Series Data

On this page

  • Overview
  • Create a Time Series Collection
  • Store Time Series Data
  • Query Time Series Data
  • Additional Information

Overview

In this guide, you can learn how to use the Java Reactive Streams driver to store and interact with time series data.

Time series data 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 could 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, pass the following parameters to the createCollection() method:

  • The name of the new collection to create

  • A CreateCollectionOptions object with the TimeSeriesOptions set with the timeSeriesOptions() method

The following example creates a time series collection named october2024 in the fall_weather database with the timeField option set to the "timestamp" field:

MongoDatabase database = mongoClient.getDatabase("fall_weather");
TimeSeriesOptions tsOptions = new TimeSeriesOptions("timestamp");
CreateCollectionOptions collectionOptions = new CreateCollectionOptions().timeSeriesOptions(tsOptions);
database.createCollection("october2024", collectionOptions);

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

ListCollectionsPublisher<Document> listCollectionsPublisher = database.listCollections();
Flux.from(listCollectionsPublisher)
        .doOnNext(System.out::println)
        .blockLast();
Document{{name=october2024, type=timeseries, options=Document{{timeseries=Document{{timeField=timestamp, granularity=seconds, bucketMaxSpanSeconds=3600}}}}, info=Document{{readOnly=false}}}}
...

Store Time Series Data

You can insert data into a time series collection by using the insertOne() or 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.

Example

The following example inserts New York City temperature data into the october2024 time series collection created in the Create a Time Series Collection example. Each document contains the following fields:

  • temperature, which stores temperature measurements in degrees Fahrenheit

  • location, which stores location metadata

  • timestamp, which stores the time of the measurement collection

MongoCollection<Document> collection = database.getCollection("october2024");
// Temperature data for October 1, 2024
Document temperature1 = new Document("temperature", 54)
        .append("location", "New York City")
        .append("timestamp", new Date(1727755200000L));
// Temperature data for October 2, 2024
Document temperature2 = new Document("temperature", 55)
        .append("location", "New York City")
        .append("timestamp", new Date(1727841600000L));
Publisher<InsertManyResult> insertPublisher =
        collection.insertMany(Arrays.asList(temperature1, temperature2));
Mono.from(insertPublisher).block();

Query Time Series Data

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 learn more 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 performing read operations, see Read Data From MongoDB.

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

API Documentation

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

Back

Specialized Data Formats