Skip to content

Commit 2b72e4c

Browse files
gmiller-mdbgmiller-mdb
authored
Merge pull request #121 from gmiller-mdb/DOCSP-45183-time-series-collections
DOCSP-45183-time-series-collections
2 parents ac9d73b + 548a9e9 commit 2b72e4c

File tree

4 files changed

+278
-0
lines changed

4 files changed

+278
-0
lines changed

Diff for: ‎source/data-formats.txt

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. _ruby-data-formats:
2+
3+
============
4+
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+
:description: Learn how to use indexes by using the MongoDB Ruby Driver.
19+
:keywords: ruby, query, collections, time series
20+
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
Time Series Data </data-formats/time-series>
26+
27+
Overview
28+
--------
29+
30+
You can use several types of specialized data formats in your {+driver-short+}
31+
application. To learn how to work with these data formats, see the following
32+
sections:
33+
34+
- :ref:`ruby-time-series`: Learn how to create a time series collection and interact with time series data.

Diff for: ‎source/data-formats/time-series.txt

+202
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
.. _ruby-time-series:
2+
3+
================
4+
Time Series Data
5+
================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: ruby, time series, collections, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use {+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+
.. _ruby-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+
To create a time series collection, you must pass an options hash that contains
67+
the specifications for the collection. You can specify the following specifications
68+
for your time series collection:
69+
70+
- ``:timeField``: Specifies the field that stores a timestamp in each time series
71+
document.
72+
- ``:metaField``: Specifies the field that stores metadata in each time series
73+
document.
74+
- ``:granularity``: Specifies the approximate time between consecutive timestamps.
75+
The possible values are ``'seconds'``, ``'minutes'``, and ``'hours'``.
76+
- ``:bucketMaxSpanSeconds``: Sets the maximum time between timestamps in the
77+
same bucket.
78+
- ``:bucketRoundingSeconds``: Sets the number of seconds to round down by when
79+
MongoDB sets the minimum timestamp for a new bucket. Must be equal to
80+
``:bucketMaxSpanSeconds``.
81+
82+
See :manual:`Command Fields </reference/command/create/#command-fields>`
83+
in the {+mdb-server+} manual entry on the ``create`` command to learn more about
84+
these parameters.
85+
86+
Example
87+
~~~~~~~
88+
89+
The following example uses the ``Collection#create`` method to create a time series
90+
collection named ``october2024`` with the ``:timeField``` option set to ``"timestamp"``:
91+
92+
.. literalinclude:: /includes/usage-examples/time-series.rb
93+
:language: ruby
94+
:dedent:
95+
:start-after: start-create
96+
:end-before: end-create
97+
98+
To verify that you have successfully created the collection, print a list of all
99+
collections in your database and filter by collection name, as shown in the following
100+
code:
101+
102+
.. io-code-block::
103+
104+
.. input:: /includes/usage-examples/time-series.rb
105+
:language: ruby
106+
:start-after: start-correct
107+
:end-before: end-correct
108+
:dedent:
109+
110+
.. output::
111+
:language: json
112+
:visible: false
113+
114+
[
115+
{
116+
"name": "october2024",
117+
"type": "timeseries",
118+
"options": {
119+
"timeseries": {
120+
"timeField": "timestamp",
121+
"granularity": "seconds",
122+
"bucketMaxSpanSeconds": 3600
123+
}
124+
},
125+
"info": {
126+
"readOnly": false
127+
}
128+
}
129+
]
130+
131+
132+
.. _ruby-time-series-write:
133+
134+
Store Time Series Data
135+
----------------------
136+
137+
You can insert data into a time series collection by using the ``insert_one``
138+
or ``insert_many`` method and specifying the measurement, timestamp, and
139+
metadata in each inserted document.
140+
141+
To learn more about inserting documents, see the :ref:`ruby-write-insert` guide.
142+
143+
Example
144+
~~~~~~~
145+
146+
This example inserts New York City temperature data into the ``october2024``
147+
time series collection created in the preceding :ref:`ruby-time-series-create`
148+
section. Each document contains the following fields:
149+
150+
- ``temperature``, which stores temperature measurements in degrees Fahrenheit
151+
- ``location``, which stores location metadata
152+
- ``timestamp``, which stores the measurement timestamp
153+
154+
.. literalinclude:: /includes/usage-examples/time-series.rb
155+
:language: ruby
156+
:dedent:
157+
:start-after: start-insert
158+
:end-before: end-insert
159+
160+
.. TODO: add link
161+
162+
.. .. tip:: Formatting Dates and Times
163+
164+
.. To learn more about using ``datetime`` objects in {+driver-short+}, see
165+
.. :ref:`ruby-dates-times`.
166+
167+
.. _ruby-time-series-read:
168+
169+
Query Time Series Data
170+
----------------------
171+
172+
You can use the same syntax and conventions to query data stored in a time
173+
series collection as you use when performing read or aggregation operations on
174+
other collections.
175+
176+
.. TODO: add links
177+
.. To learn more about these operations, see :ref:`ruby-read`
178+
.. and :ref:`ruby-aggregation`.
179+
180+
.. _ruby-time-series-addtl-info:
181+
182+
Additional Information
183+
----------------------
184+
185+
To learn more about the concepts in this guide, see the following {+mdb-server+}
186+
manual entries:
187+
188+
- :manual:`Time Series </core/timeseries-collections/>`
189+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
190+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
191+
192+
API Documentation
193+
~~~~~~~~~~~~~~~~~
194+
195+
To learn more about the methods mentioned in this guide, see the following
196+
API documentation:
197+
198+
- `create <{+api-root+}/Mongo/Collection.html#create-instance_method>`__
199+
- `list_collections <{+api-root+}/Mongo/Database.html#list_collections-instance_method>`__
200+
- `insert_one <{+api-root+}/Mongo/Collection.html#insert_one-instance_method>`__
201+
- `insert_many <{+api-root+}/Mongo/Collection.html#insert_many-instance_method>`__
202+

Diff for: ‎source/includes/usage-examples/time-series.rb

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
require 'bundler/inline'
2+
gemfile do
3+
source 'https://rubygems.org'
4+
gem 'mongo'
5+
end
6+
7+
8+
# start-create
9+
client = Mongo::Client.new('<connection string>', database: 'weather')
10+
collection_name = 'october2024'
11+
12+
time_series_options = { timeField: 'timestamp' }
13+
database = client.database
14+
database.command(
15+
create: collection_name,
16+
timeseries: time_series_options
17+
)
18+
# end-create
19+
20+
# start-correct
21+
collections = database.list_collections(filter: { name: 'october2024' }).to_a
22+
puts collections
23+
# end-correct
24+
25+
# start-insert
26+
client = Mongo::Client.new('<connection string>', database => 'your_db')
27+
collection = client[:october2024]
28+
29+
document_list = [
30+
{ temperature: 77, location: "New York City", timestamp: DateTime.new(2024, 10, 22, 6, 0, 0) },
31+
{ temperature: 74, location: "New York City", timestamp: DateTime.new(2024, 10, 23, 6, 0, 0) }
32+
]
33+
34+
collection.insert_many(document_list)
35+
#end-insert

Diff for: ‎source/index.txt

+7
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
Read Data </read>
1919
Operations on Replica Sets </read-write-pref>
2020
Indexes </indexes>
21+
Data Formats </data-formats>
2122
View the Source <https://github.com/mongodb/mongo-ruby-driver>
2223
API Documentation <{+api-root+}>
2324
What's New </whats-new>
@@ -90,6 +91,12 @@ Learn how to configure read and write operations on a replica set in the
9091
.. Learn how to authenticate your application and encrypt your data in the
9192
.. :ref:`ruby-security` section.
9293

94+
Specialized Data Formats
95+
------------------------
96+
97+
Learn how to work with specialized data formats and custom types in the
98+
:ref:`ruby-data-formats` section.
99+
93100
What's New
94101
----------
95102

0 commit comments

Comments
 (0)