diff --git a/source/data-formats.txt b/source/data-formats.txt index 660332d3..33c81793 100644 --- a/source/data-formats.txt +++ b/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 ` 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. diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 0e64c563..afa1a43a 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -1,8 +1,8 @@ .. _kotlin-sync-bson: -========================== -Document Data Format: BSON -========================== +==== +BSON +==== .. contents:: On this page :local: diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt new file mode 100644 index 00000000..6f7d754b --- /dev/null +++ b/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 with the `TimeSeriesOptions <{+core-api+}/com/mongodb/client/model/TimeSeriesOptions.html>`__ set + using the ``timeSeriesOptions()`` method + +.. _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 +`. 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 ` section. + +.. _kotlin-sync-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 ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +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>`__ \ No newline at end of file diff --git a/source/includes/data-formats/time-series.kt b/source/includes/data-formats/time-series.kt new file mode 100644 index 00000000..b57b28d5 --- /dev/null +++ b/source/includes/data-formats/time-series.kt @@ -0,0 +1,54 @@ +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 = "" + + 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 tsOptions = TimeSeriesOptions("timestamp") + val collectionOptions = CreateCollectionOptions().timeSeriesOptions(tsOptions) + + database.createCollection("october2024", collectionOptions) + // end-create-time-series + + // start-print-time-series + val results = database.listCollections() + val jsonSettings = JsonWriterSettings.builder().indent(true).build() + + results.forEach { result -> + println(result.toJson(jsonSettings)) + } + // end-print-time-series + + // start-insert-time-series-data + val collection = database.getCollection("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 +} +