diff --git a/snooty.toml b/snooty.toml index 23ecc14..d8bfb98 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,6 +14,7 @@ toc_landing_pages = [ "/write-data-to-mongo/", "/getting-started/", "/secure-your-data/", + "/data-formats/", "/upgrade/" ] diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 0000000..b2e597f --- /dev/null +++ b/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. diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt new file mode 100644 index 0000000..5ba8f68 --- /dev/null +++ b/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 +`. 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 ` 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 ` +- :manual:`Create and Query a Time Series Collection ` +- :manual:`Set Granularity for Time Series Data ` + +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)>`__ \ No newline at end of file diff --git a/source/includes/data-formats/time-series.java b/source/includes/data-formats/time-series.java new file mode 100644 index 0000000..fd04857 --- /dev/null +++ b/source/includes/data-formats/time-series.java @@ -0,0 +1,64 @@ +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.client.result.InsertManyResult; +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 = ""; + + 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 listCollectionsPublisher = database.listCollections(); + + Flux.from(listCollectionsPublisher) + .doOnNext(System.out::println) + .blockLast(); + // end-print-time-series + + // start-insert-time-series-data + MongoCollection 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 insertPublisher = + collection.insertMany(Arrays.asList(temperature1, temperature2)); + Mono.from(insertPublisher).block(); + // end-insert-time-series-data + } + } +} \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index d0a1aa0..c538ec4 100644 --- a/source/index.txt +++ b/source/index.txt @@ -29,6 +29,7 @@ MongoDB Java Reactive Streams Documentation /indexes /aggregation /secure-your-data + /data-formats /logging /monitoring /validate-signatures @@ -92,6 +93,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 ----------