Skip to content

Commit 5be1bc9

Browse files
rustagirrustagir
authored
DOCSP-30551: time series (#63)
1 parent d222951 commit 5be1bc9

File tree

4 files changed

+217
-2
lines changed

4 files changed

+217
-2
lines changed

‎source/fundamentals.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Fundamentals
1818
/fundamentals/schema-validation
1919
/fundamentals/aggregation
2020
/fundamentals/indexes
21+
/fundamentals/time-series
2122
/fundamentals/tracing-logging
2223
/fundamentals/run-command
2324
/fundamentals/performance
@@ -29,7 +30,6 @@ Fundamentals
2930
/fundamentals/collations
3031
/fundamentals/monitoring
3132
/fundamentals/gridfs
32-
/fundamentals/time-series
3333
/fundamentals/encrypt-fields
3434
/fundamentals/geo
3535

‎source/fundamentals/time-series.txt

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
.. _rust-time-series:
2+
3+
=======================
4+
Time Series Collections
5+
=======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to use the {+driver-short+} to create
17+
and interact with **time series collections**. Time series collections
18+
efficiently store chronological sequences of measurements over a period
19+
of time. Each document in a time series collection contains the
20+
following pieces of information:
21+
22+
- Quantity that is being measured over time
23+
- Metadata that describes the measurement
24+
- Timestamp for the measurement
25+
26+
The following table describes some sample situations for which data could be
27+
stored in a time series collection. Each row describes the situation,
28+
the measured quantity, and the metadata in each document:
29+
30+
.. list-table::
31+
:widths: 40, 30, 30
32+
:header-rows: 1
33+
:stub-columns: 1
34+
35+
* - Situation
36+
- Measured Quantity
37+
- Metadata
38+
39+
* - Recording monthly sales by industry
40+
- Revenue in USD
41+
- Company, country
42+
43+
* - Tracking weather changes
44+
- Precipitation level
45+
- Location, sensor type
46+
47+
* - Recording fluctuations in housing prices
48+
- Monthly rent price
49+
- Location, currency
50+
51+
This guide includes the following sections:
52+
53+
- :ref:`Create a Time Series Collection <rust-tseries-create>` describes
54+
the syntax for creating a time series collection and provides example code
55+
56+
- :ref:`Query a Time Series Collection <rust-tseries-query>` describes how to
57+
perform operations on time series collections
58+
59+
- :ref:`Additional Information <rust-tseries-addtl-info>`
60+
provides links to resources and API documentation for types
61+
and methods mentioned in this guide
62+
63+
.. _rust-tseries-create:
64+
65+
Create a Time Series Collection
66+
-------------------------------
67+
68+
.. important:: Server Version for Time Series Collections
69+
70+
To create and interact with time series collections, you must be
71+
connected to a deployment running MongoDB 5.0 or later.
72+
73+
74+
To create a time series collection, perform the following actions:
75+
76+
1. Create a ``TimeseriesOptions`` instance that specifies properties of
77+
your time series collection.
78+
79+
#. Create a ``CreateCollectionOptions`` instance and set the value of
80+
the ``timeseries`` field to your ``TimeseriesOptions`` instance.
81+
82+
#. Pass the ``CreateCollectionOptions`` instance to the
83+
``create_collection()`` method. You must also pass the collection
84+
name as a parameter.
85+
86+
Example
87+
~~~~~~~
88+
89+
This example creates the ``sept2023`` time series collection in the
90+
``precipitation`` database with the following configuration:
91+
92+
- ``time_field`` is set to ``"precipitation_mm"``
93+
- ``meta_field`` is set to ``"location"``
94+
- ``granularity`` is set to minutes
95+
96+
.. literalinclude:: /includes/fundamentals/code-snippets/tseries.rs
97+
:start-after: begin-create-ts
98+
:end-before: end-create-ts
99+
:language: rust
100+
:dedent:
101+
102+
To verify that you successfully created the time series collection, run
103+
the ``list_collections()`` method on the database and print the results:
104+
105+
.. io-code-block::
106+
:copyable: true
107+
108+
.. input:: /includes/fundamentals/code-snippets/tseries.rs
109+
:start-after: begin-list-colls
110+
:end-before: end-list-colls
111+
:language: rust
112+
:dedent:
113+
114+
.. output::
115+
:language: console
116+
:visible: false
117+
118+
CollectionSpecification {
119+
name: "sept2023",
120+
collection_type: Timeseries,
121+
options: CreateCollectionOptions {
122+
...
123+
timeseries: Some(
124+
TimeseriesOptions {
125+
time_field: "precipitation_mm",
126+
meta_field: Some(
127+
"location",
128+
),
129+
granularity: Some(
130+
Minutes,
131+
),
132+
},
133+
),
134+
...
135+
},
136+
...
137+
}
138+
139+
.. _rust-tseries-query:
140+
141+
Query a Time Series Collection
142+
------------------------------
143+
144+
You can use the same syntax and conventions to query a time series
145+
collection as you use when performing read or aggregation operations on
146+
other collections. To find more information about these operations, see
147+
the :ref:`Additional Information <rust-tseries-addtl-info>` section.
148+
149+
.. _rust-tseries-addtl-info:
150+
151+
Additional Information
152+
----------------------
153+
154+
To learn more about the concepts mentioned in this guide, see the
155+
following Server manual entries:
156+
157+
- :manual:`Time Series </core/timeseries-collections/>`
158+
- :manual:`Create and Query a Time Series Collection </core/timeseries/timeseries-procedures/>`
159+
- :manual:`Set Granularity for Time Series Data </core/timeseries/timeseries-granularity/>`
160+
161+
To learn more about creating collections, see the guide on
162+
:ref:`rust-db-coll`.
163+
164+
To learn more about performing read operations, see the guides in the
165+
:ref:`rust-crud-read-operations` category.
166+
167+
API Documentation
168+
~~~~~~~~~~~~~~~~~
169+
170+
To learn more about the methods and types mentioned in this
171+
guide, see the following API documentation:
172+
173+
- `TimeseriesOptions <{+api+}/options/struct.TimeseriesOptions.html>`__
174+
- `CreateCollectionOptions <{+api+}/options/struct.CreateCollectionOptions.html>`__
175+
- `create_collection() <{+api+}/struct.Database.html#method.create_collection>`__
176+
- `TimeseriesGranularity <{+api+}/options/enum.TimeseriesGranularity.html>`__
177+
- `list_collections() <{+api+}/struct.Database.html#method.list_collections>`__
178+
- `CollectionSpecification <{+api+}/results/struct.CollectionSpecification.html>`__

‎source/includes/fundamentals-sections.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Fundamentals section:
1111
- :ref:`Implement Schema Validation <rust-schema-validation>`
1212
- :ref:`Perform Aggregations <rust-aggregation>`
1313
- :ref:`Create and Manage Indexes <rust-indexes>`
14+
- :ref:`Create a Time Series Collection <rust-time-series>`
1415
- :ref:`Record Driver Events <rust-tracing-logging>`
1516
- :ref:`Run A Database Command <rust-run-command>`
1617
- :ref:`Optimize Driver Performance <rust-performance>`
@@ -21,6 +22,5 @@ Fundamentals section:
2122
- :ref:`Specify Collations to Order Results <rust-collations>`
2223
- :ref:`Monitor Driver Events <rust-monitoring>`
2324
- :ref:`Store and Retrieve Large Files by Using GridFS <rust-gridfs>`
24-
- :ref:`Use a Time Series Collection <rust-time-series>`
2525
- :ref:`Encrypt Fields <rust-fle>`
2626
- :ref:`Query and Write Geospatial Data <rust-geo>`

‎source/includes/fundamentals/code-snippets/tseries.rs

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
use futures::TryStreamExt;
2+
use mongodb::{
3+
options::{ TimeseriesOptions, TimeseriesGranularity, CreateCollectionOptions },
4+
Client,
5+
};
6+
use std::env;
7+
8+
#[tokio::main]
9+
async fn main() -> mongodb::error::Result<()> {
10+
let uri = "<connection string>";
11+
let client = Client::with_uri_str(uri).await?;
12+
13+
// begin-create-ts
14+
let db = client.database("precipitation");
15+
16+
let ts_opts = TimeseriesOptions::builder()
17+
.time_field("precipitation_mm".to_string())
18+
.meta_field(Some("location".to_string()))
19+
.granularity(Some(TimeseriesGranularity::Minutes))
20+
.build();
21+
22+
let coll_opts = CreateCollectionOptions::builder()
23+
.timeseries(ts_opts)
24+
.build();
25+
26+
db.create_collection("sept2023", coll_opts).await?;
27+
// end-create-ts
28+
29+
// begin-list-colls
30+
let mut coll_list = db.list_collections(None, None).await?;
31+
while let Some(c) = coll_list.try_next().await? {
32+
println!("{:#?}", c);
33+
}
34+
// end-list-colls
35+
36+
Ok(())
37+
}

0 commit comments

Comments
 (0)