DOCSP-42297: Time Series

snooty.toml

@@ -12,7 +12,8 @@ toc_landing_pages = [
     "/read-data-from-mongo/",
     "/write-data-to-mongo/",
     "/getting-started/",
-    "/secure-your-data/"
+    "/secure-your-data/",
+    "/data-formats/"
     ]
 
 [constants]

source/data-formats.txt

@@ -0,0 +1,33 @@
+.. _java-rs-data-formats:
+
+========================
+Specialized Data Formats
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: bson, data, class, date, time 
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /data-formats/time-series
+
+Overview
+--------
+
+You can use several types of specialized document data formats in your {+driver-short+}
+application. To learn how to work with these data formats, see the following
+sections:
+
+- Learn how to store and interact with time series data in the :ref:`java-rs-time-series` guide.

source/data-formats/time-series.txt

@@ -0,0 +1,171 @@
+.. _java-rs-time-series:
+
+================
+Time Series Data
+================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, measurement, weather
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the {+driver-short+} 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:
+
+.. list-table::
+   :widths: 33, 33, 33
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - 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
+
+.. _java-rs-time-series-create:
+
+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 {+mdb-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 <{+api+}/mongodb-driver-core/com/mongodb/client/model/CreateCollectionOptions.html>`__
+  object with the `TimeSeriesOptions <{+api+}/mongodb-driver-core/com/mongodb/client/model/TimeSeriesOptions.html>`__ set
+  with the ``timeSeriesOptions()`` method
+
+.. _java-rs-time-series-create-example:
+
+The following example creates a time series collection named ``october2024`` in the
+``fall_weather`` database with the ``timeField`` option set to the ``"timestamp"`` field:
+
+.. literalinclude:: /includes/data-formats/time-series.java
+   :language: java
+   :start-after: start-create-time-series
+   :end-before: end-create-time-series
+   :dedent:
+
+To verify that you successfully created the time series collection, run
+the ``listCollections()`` method on the database and print the results:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/data-formats/time-series.java
+      :language: java
+      :start-after: start-print-time-series
+      :end-before: end-print-time-series
+      :dedent:
+
+   .. output::
+
+      Document{{name=october2024, type=timeseries, options=Document{{timeseries=Document{{timeField=timestamp, granularity=seconds, bucketMaxSpanSeconds=3600}}}}, info=Document{{readOnly=false}}}}
+      ...
+
+.. _java-rs-time-series-store:
+
+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 :ref:`java-rs-write-insert`
+   guide.
+
+Example
+~~~~~~~
+
+The following example inserts New York City temperature data into the ``october2024``
+time series collection created in the :ref:`Create a Time Series Collection example
+<java-rs-time-series-create-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
+
+.. literalinclude:: /includes/data-formats/time-series.java
+   :language: java
+   :start-after: start-insert-time-series-data
+   :end-before: end-insert-time-series-data
+   :dedent:
+
+.. _java-rs-time-series-query:
+
+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 :ref:`Additional Information <java-rs-time-series-addtl-info>` section.
+
+.. _java-rs-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the
+following {+mdb-server+} manual entries:
+
+- :manual:`Time Series </core/timeseries-collections/>`
+- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
+- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
+
+To learn more about performing read operations, see :ref:`java-rs-read`.
+
+To learn more about performing aggregation operations, see the :ref:`java-rs-aggregation`
+guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods mentioned in this guide, see the following
+API documentation:
+
+- `createCollection() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#createCollection(java.lang.String)>`__
+- `listCollections() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#listCollections()>`__
+- `insertOne() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#insertOne(TDocument)>`__
+- `insertMany() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#insertMany(java.util.List)>`__

source/includes/data-formats/time-series.java

@@ -0,0 +1,61 @@
+package org.example;
+
+import com.mongodb.ConnectionString;
+import com.mongodb.MongoClientSettings;
+
+import com.mongodb.client.model.CreateCollectionOptions;
+import com.mongodb.client.model.TimeSeriesOptions;
+import com.mongodb.reactivestreams.client.*;
+import org.bson.Document;
+import reactor.core.publisher.Flux;
+
+import java.util.Arrays;
+import java.util.Date;
+
+public class Main {
+    public static void main(String[] args) {
+
+        // Replace the placeholder with your Atlas connection string
+        String uri = "<connection string URI>";
+
+        MongoClientSettings settings = MongoClientSettings.builder()
+                .applyConnectionString(new ConnectionString(uri))
+                .build();
+
+        // Create a new client and connect to the server
+        try (MongoClient mongoClient = MongoClients.create(settings)) {
+            // start-create-time-series
+            MongoDatabase database = mongoClient.getDatabase("fall_weather");
+
+            TimeSeriesOptions tsOptions = new TimeSeriesOptions("timestamp");
+            CreateCollectionOptions collectionOptions = new CreateCollectionOptions().timeSeriesOptions(tsOptions);
+
+            database.createCollection("october2024", collectionOptions);
+            // end-create-time-series
+
+            // start-print-time-series
+            ListCollectionsPublisher<Document> listCollectionsPublisher = database.listCollections();
+
+            Flux.from(listCollectionsPublisher)
+                    .doOnNext(System.out::println)
+                    .blockLast();
+            // end-print-time-series
+
+            // start-insert-time-series-data
+            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));
+
+            collection.insertMany(Arrays.asList(temperature1, temperature2));
+            // end-insert-time-series-data
+        }
+    }
+}

source/index.txt

@@ -29,6 +29,7 @@ MongoDB Java Reactive Streams Documentation
    /indexes
    /aggregation
    /secure-your-data
+   /data-formats
    /logging
    /monitoring
    /validate-signatures
@@ -91,6 +92,12 @@ Secure Your Data
 Learn about ways you can authenticate your application and encrypt your data in
 the :ref:`java-rs-security` section.
 
+Specialized Data Formats
+------------------------
+
+Learn how to work with specialized data formats and custom types in the
+:ref:`java-rs-data-formats` section.
+
 What's New
 ----------