DOCSP-41152: Time Series

source/data-formats.txt

@@ -22,10 +22,10 @@ Specialized Data Formats
    :maxdepth: 1
 
    /data-formats/bson
+   /data-formats/time-series
 
 ..     TODO: /data-formats/data-class
 ..     TODO: /data-formats/extended-json
-..     TODO: /data-formats/time-series
 
 Overview
 --------
@@ -34,9 +34,9 @@ You can use several types of specialized document data formats in your {+driver-
 application. To learn how to work with these data formats, see the following
 sections:
 
-- Learn how to work with the BSON data format in the :ref:`BSON <kotlin-sync-bson>` guide.
+- Learn how to work with the BSON data format in the :ref:`kotlin-sync-bson` guide.
+- Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.
 
 .. TODO: Uncomment these as pages get built
 .. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
 .. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.
-.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.

source/data-formats/bson.txt

@@ -1,8 +1,8 @@
 .. _kotlin-sync-bson:
 
-==========================
-Document Data Format: BSON
-==========================
+====
+BSON
+====
 
 .. contents:: On this page
    :local:

source/data-formats/time-series.txt

@@ -0,0 +1,181 @@
+.. _kotlin-sync-time-series:
+
+================
+Time Series Data
+================
+
+.. 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
+
+.. _cpp-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 <{+core-api+}/com/mongodb/client/model/CreateCollectionOptions.html>`__
+  object containing the `TimeSeriesOptions <{+core-api+}/com/mongodb/client/model/TimeSeriesOptions.html>`__ object
+  for creating your collection
+
+.. _kotlin-sync-time-series-create-example:
+
+Example
+~~~~~~~
+
+This example creates the ``october2024`` time series collection in the
+``fall_weather`` database with the ``timeField`` option set to the ``"timestamp"`` field:
+
+.. literalinclude:: /includes/data-formats/time-series.kt
+   :language: kotlin
+   :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.kt
+      :language: kotlin
+      :start-after: start-print-time-series
+      :end-before: end-print-time-series
+      :dedent:
+
+   .. output::
+
+      {
+        "name": "october2024",
+        "type": "timeseries",
+        "options": {
+          "timeseries": {
+            "timeField": "temperature",
+            "granularity": "seconds",
+            "bucketMaxSpanSeconds": 3600
+          }
+        },
+        "info": {
+          "readOnly": false
+        }
+     }
+     ...
+
+.. _kotlin-sync-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.
+
+.. TODO: Uncomment when insert guide is created
+.. .. tip::
+
+..    To learn more about inserting documents into a collection, see the :ref:`kotlin-sync-write-insert`
+..    guide.
+
+Example
+~~~~~~~
+
+This example inserts New York City temperature data into the ``october2024``
+time series collection created in the :ref:`Create a Time Series Collection example
+<kotlin-sync-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.kt
+   :language: kotlin
+   :start-after: start-insert-time-series-data
+   :end-before: end-insert-time-series-data
+   :dedent:
+
+.. _kotlin-sync-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 <kotlin-sync-time-series-addtl-info>` section.
+
+.. _kotlin-sync-time-series-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about the concepts mentioned in this guide, see the
+following 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:`kotlin-sync-read`.
+
+.. TODO: To learn more about performing aggregation operations, see the :ref:`kotlin-sync-aggregation`
+.. guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods mentioned in this guide, see the following
+API documentation:
+
+- `createCollection() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/create-collection.html>`__
+- `listCollections() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/list-collections.html>`__
+- `insertOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-one.html>`__
+- `insertMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/insert-many.html>`__

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

@@ -0,0 +1,53 @@
+package org.example
+import com.mongodb.ConnectionString
+import com.mongodb.MongoClientSettings
+import com.mongodb.client.model.*
+import com.mongodb.kotlin.client.MongoClient
+import org.bson.json.JsonWriterSettings
+import java.util.Date
+import org.bson.Document
+
+fun main() {
+    val uri = "<connection string URI>"
+
+    val settings = MongoClientSettings.builder()
+        .applyConnectionString(ConnectionString(uri))
+        .retryWrites(true)
+        .build()
+
+    val mongoClient = MongoClient.create(settings)
+
+    // start-create-time-series
+    val database = mongoClient.getDatabase("fall_weather")
+
+    val timeSeriesOptions = TimeSeriesOptions("timestamp")
+    val collectionOptions = CreateCollectionOptions().timeSeriesOptions(timeSeriesOptions)
+
+    database.createCollection("october2024", collectionOptions)
+    // end-create-time-series
+
+    // start-print-time-series
+    val results = database.listCollections()
+
+    results.forEach { result ->
+        println(result.toJson(JsonWriterSettings.builder().indent(true).build()))
+    }
+    // end-print-time-series
+
+    // start-insert-time-series-data
+    val collection = database.getCollection<Document>("october2024")
+
+    // Temperature data for October 1, 2024
+    val temperature1 = Document("temperature", 54)
+                        .append("location", "New York City")
+                        .append("timestamp", Date(1727755200000))
+
+    // Temperature data for October 2, 2024
+    val temperature2 = Document("temperature", 55)
+                        .append("location", "New York City")
+                        .append("timestamp", Date(1727841600000))
+
+    collection.insertMany(listOf(temperature1, temperature2))
+    // end-insert-time-series-data
+}
+