Skip to content

Commit 2a6232a

Browse files
mcmorisimcmorisi
authored
DOCSP-42297: Time Series (#78)
1 parent 72c693c commit 2a6232a

File tree

5 files changed

+276
-0
lines changed

5 files changed

+276
-0
lines changed

‎snooty.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ toc_landing_pages = [
1414
"/write-data-to-mongo/",
1515
"/getting-started/",
1616
"/secure-your-data/",
17+
"/data-formats/",
1718
"/upgrade/"
1819
]
1920

‎source/data-formats.txt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. _java-rs-data-formats:
2+
3+
========================
4+
Specialized Data Formats
5+
========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: bson, data, class, date, time
19+
20+
.. toctree::
21+
:titlesonly:
22+
:maxdepth: 1
23+
24+
/data-formats/time-series
25+
26+
Overview
27+
--------
28+
29+
You can use several types of specialized document data formats in your {+driver-short+}
30+
application. To learn how to work with these data formats, see the following
31+
sections:
32+
33+
- Learn how to store and interact with time series data in the :ref:`java-rs-time-series` guide.

‎source/data-formats/time-series.txt‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
.. _java-rs-time-series:
2+
3+
================
4+
Time Series Data
5+
================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, measurement, weather
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to store
24+
and interact with **time series data**.
25+
26+
Time series data is composed of the following components:
27+
28+
- Measured quantity
29+
- Timestamp for the measurement
30+
- Metadata that describes the measurement
31+
32+
The following table describes sample situations for which you could store time
33+
series data:
34+
35+
.. list-table::
36+
:widths: 33, 33, 33
37+
:header-rows: 1
38+
:stub-columns: 1
39+
40+
* - Situation
41+
- Measured Quantity
42+
- Metadata
43+
44+
* - Recording monthly sales by industry
45+
- Revenue in USD
46+
- Company, country
47+
48+
* - Tracking weather changes
49+
- Precipitation level
50+
- Location, sensor type
51+
52+
* - Recording fluctuations in housing prices
53+
- Monthly rent price
54+
- Location, currency
55+
56+
.. _java-rs-time-series-create:
57+
58+
Create a Time Series Collection
59+
-------------------------------
60+
61+
.. important:: Server Version for Time Series Collections
62+
63+
To create and interact with time series collections, you must be
64+
connected to a deployment running {+mdb-server+} 5.0 or later.
65+
66+
You can create a time series collection to store time series data.
67+
To create a time series collection, pass the following parameters to the
68+
``createCollection()`` method:
69+
70+
- The name of the new collection to create
71+
72+
- A `CreateCollectionOptions <{+api+}/mongodb-driver-core/com/mongodb/client/model/CreateCollectionOptions.html>`__
73+
object with the `TimeSeriesOptions <{+api+}/mongodb-driver-core/com/mongodb/client/model/TimeSeriesOptions.html>`__ set
74+
with the ``timeSeriesOptions()`` method
75+
76+
.. _java-rs-time-series-create-example:
77+
78+
The following example creates a time series collection named ``october2024`` in the
79+
``fall_weather`` database with the ``timeField`` option set to the ``"timestamp"`` field:
80+
81+
.. literalinclude:: /includes/data-formats/time-series.java
82+
:language: java
83+
:start-after: start-create-time-series
84+
:end-before: end-create-time-series
85+
:dedent:
86+
87+
To verify that you successfully created the time series collection, run
88+
the ``listCollections()`` method on the database and print the results:
89+
90+
.. io-code-block::
91+
:copyable: true
92+
93+
.. input:: /includes/data-formats/time-series.java
94+
:language: java
95+
:start-after: start-print-time-series
96+
:end-before: end-print-time-series
97+
:dedent:
98+
99+
.. output::
100+
101+
Document{{name=october2024, type=timeseries, options=Document{{timeseries=Document{{timeField=timestamp, granularity=seconds, bucketMaxSpanSeconds=3600}}}}, info=Document{{readOnly=false}}}}
102+
...
103+
104+
.. _java-rs-time-series-store:
105+
106+
Store Time Series Data
107+
----------------------
108+
109+
You can insert data into a time series collection by using the ``insertOne()``
110+
or ``insertMany()`` methods and specifying the measurement, timestamp, and metadata
111+
in each inserted document.
112+
113+
.. tip::
114+
115+
To learn more about inserting documents into a collection, see the :ref:`java-rs-write-insert`
116+
guide.
117+
118+
Example
119+
~~~~~~~
120+
121+
The following example inserts New York City temperature data into the ``october2024``
122+
time series collection created in the :ref:`Create a Time Series Collection example
123+
<java-rs-time-series-create-example>`. Each document contains the following fields:
124+
125+
- ``temperature``, which stores temperature measurements in degrees Fahrenheit
126+
- ``location``, which stores location metadata
127+
- ``timestamp``, which stores the time of the measurement collection
128+
129+
.. literalinclude:: /includes/data-formats/time-series.java
130+
:language: java
131+
:start-after: start-insert-time-series-data
132+
:end-before: end-insert-time-series-data
133+
:dedent:
134+
135+
.. _java-rs-time-series-query:
136+
137+
Query Time Series Data
138+
----------------------
139+
140+
You can use the same syntax and conventions to query data stored in a time
141+
series collection as you use when performing read or aggregation operations on
142+
other collections. To learn more about these operations, see
143+
the :ref:`Additional Information <java-rs-time-series-addtl-info>` section.
144+
145+
.. _java-rs-time-series-addtl-info:
146+
147+
Additional Information
148+
----------------------
149+
150+
To learn more about the concepts mentioned in this guide, see the
151+
following {+mdb-server+} manual entries:
152+
153+
- :manual:`Time Series </core/timeseries-collections/>`
154+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
155+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
156+
157+
To learn more about performing read operations, see :ref:`java-rs-read`.
158+
159+
To learn more about performing aggregation operations, see the :ref:`java-rs-aggregation`
160+
guide.
161+
162+
API Documentation
163+
~~~~~~~~~~~~~~~~~
164+
165+
To learn more about the methods mentioned in this guide, see the following
166+
API documentation:
167+
168+
- `createCollection() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#createCollection(java.lang.String)>`__
169+
- `listCollections() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoDatabase.html#listCollections()>`__
170+
- `insertOne() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#insertOne(TDocument)>`__
171+
- `insertMany() <{+api+}/mongodb-driver-reactivestreams/com/mongodb/reactivestreams/client/MongoCollection.html#insertMany(java.util.List)>`__

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
package org.example;
2+
3+
import com.mongodb.ConnectionString;
4+
import com.mongodb.MongoClientSettings;
5+
6+
import com.mongodb.client.model.CreateCollectionOptions;
7+
import com.mongodb.client.model.TimeSeriesOptions;
8+
import com.mongodb.client.result.InsertManyResult;
9+
import com.mongodb.reactivestreams.client.*;
10+
import org.bson.Document;
11+
import reactor.core.publisher.Flux;
12+
13+
import java.util.Arrays;
14+
import java.util.Date;
15+
16+
public class Main {
17+
public static void main(String[] args) {
18+
19+
// Replace the placeholder with your Atlas connection string
20+
String uri = "<connection string URI>";
21+
22+
MongoClientSettings settings = MongoClientSettings.builder()
23+
.applyConnectionString(new ConnectionString(uri))
24+
.build();
25+
26+
// Create a new client and connect to the server
27+
try (MongoClient mongoClient = MongoClients.create(settings)) {
28+
// start-create-time-series
29+
MongoDatabase database = mongoClient.getDatabase("fall_weather");
30+
31+
TimeSeriesOptions tsOptions = new TimeSeriesOptions("timestamp");
32+
CreateCollectionOptions collectionOptions = new CreateCollectionOptions().timeSeriesOptions(tsOptions);
33+
34+
database.createCollection("october2024", collectionOptions);
35+
// end-create-time-series
36+
37+
// start-print-time-series
38+
ListCollectionsPublisher<Document> listCollectionsPublisher = database.listCollections();
39+
40+
Flux.from(listCollectionsPublisher)
41+
.doOnNext(System.out::println)
42+
.blockLast();
43+
// end-print-time-series
44+
45+
// start-insert-time-series-data
46+
MongoCollection<Document> collection = database.getCollection("october2024");
47+
48+
// Temperature data for October 1, 2024
49+
Document temperature1 = new Document("temperature", 54)
50+
.append("location", "New York City")
51+
.append("timestamp", new Date(1727755200000L));
52+
53+
// Temperature data for October 2, 2024
54+
Document temperature2 = new Document("temperature", 55)
55+
.append("location", "New York City")
56+
.append("timestamp", new Date(1727841600000L));
57+
58+
Publisher<InsertManyResult> insertPublisher =
59+
collection.insertMany(Arrays.asList(temperature1, temperature2));
60+
Mono.from(insertPublisher).block();
61+
// end-insert-time-series-data
62+
}
63+
}
64+
}

‎source/index.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ MongoDB Java Reactive Streams Documentation
2929
/indexes
3030
/aggregation
3131
/secure-your-data
32+
/data-formats
3233
/logging
3334
/monitoring
3435
/validate-signatures
@@ -92,6 +93,12 @@ Secure Your Data
9293
Learn about ways you can authenticate your application and encrypt your data in
9394
the :ref:`java-rs-security` section.
9495

96+
Specialized Data Formats
97+
------------------------
98+
99+
Learn how to work with specialized data formats and custom types in the
100+
:ref:`java-rs-data-formats` section.
101+
95102
What's New
96103
----------
97104

0 commit comments

Comments
 (0)