Skip to content

Commit c8d9955

Browse files
mcmorisimcmorisi
authored
DOCSP-41152: Time Series (#23)
1 parent 5a83299 commit c8d9955

File tree

4 files changed

+241
-6
lines changed

4 files changed

+241
-6
lines changed

‎source/data-formats.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,10 @@ Specialized Data Formats
2222
:maxdepth: 1
2323

2424
/data-formats/bson
25+
/data-formats/time-series
2526

2627
.. TODO: /data-formats/data-class
2728
.. TODO: /data-formats/extended-json
28-
.. TODO: /data-formats/time-series
2929

3030
Overview
3131
--------
@@ -34,9 +34,9 @@ You can use several types of specialized document data formats in your {+driver-
3434
application. To learn how to work with these data formats, see the following
3535
sections:
3636

37-
- Learn how to work with the BSON data format in the :ref:`BSON <kotlin-sync-bson>` guide.
37+
- Learn how to work with the BSON data format in the :ref:`kotlin-sync-bson` guide.
38+
- Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.
3839

3940
.. TODO: Uncomment these as pages get built
4041
.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
4142
.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.
42-
.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.

‎source/data-formats/bson.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _kotlin-sync-bson:
22

3-
==========================
4-
Document Data Format: BSON
5-
==========================
3+
====
4+
BSON
5+
====
66

77
.. contents:: On this page
88
:local:

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

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

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
package org.example
2+
import com.mongodb.ConnectionString
3+
import com.mongodb.MongoClientSettings
4+
import com.mongodb.client.model.*
5+
import com.mongodb.kotlin.client.MongoClient
6+
import org.bson.json.JsonWriterSettings
7+
import java.util.Date
8+
import org.bson.Document
9+
10+
fun main() {
11+
val uri = "<connection string URI>"
12+
13+
val settings = MongoClientSettings.builder()
14+
.applyConnectionString(ConnectionString(uri))
15+
.retryWrites(true)
16+
.build()
17+
18+
val mongoClient = MongoClient.create(settings)
19+
20+
// start-create-time-series
21+
val database = mongoClient.getDatabase("fall_weather")
22+
23+
val tsOptions = TimeSeriesOptions("timestamp")
24+
val collectionOptions = CreateCollectionOptions().timeSeriesOptions(tsOptions)
25+
26+
database.createCollection("october2024", collectionOptions)
27+
// end-create-time-series
28+
29+
// start-print-time-series
30+
val results = database.listCollections()
31+
val jsonSettings = JsonWriterSettings.builder().indent(true).build()
32+
33+
results.forEach { result ->
34+
println(result.toJson(jsonSettings))
35+
}
36+
// end-print-time-series
37+
38+
// start-insert-time-series-data
39+
val collection = database.getCollection<Document>("october2024")
40+
41+
// Temperature data for October 1, 2024
42+
val temperature1 = Document("temperature", 54)
43+
.append("location", "New York City")
44+
.append("timestamp", Date(1727755200000))
45+
46+
// Temperature data for October 2, 2024
47+
val temperature2 = Document("temperature", 55)
48+
.append("location", "New York City")
49+
.append("timestamp", Date(1727841600000))
50+
51+
collection.insertMany(listOf(temperature1, temperature2))
52+
// end-insert-time-series-data
53+
}
54+

0 commit comments

Comments
 (0)