Skip to content

Commit 6a574d8

Browse files
lindseymoorelindseymoore
authored
Merge branch 'standardization' into DOCSP-45179
2 parents b64d746 + 76c5922 commit 6a574d8

36 files changed

+3268
-17
lines changed

‎snooty.toml

+3-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ toc_landing_pages = [
44
"/get-started",
55
"/connect",
66
"/write",
7-
"/indexes"
7+
"/indexes",
8+
"/databases-collection",
9+
"/security/authentication"
810
]
911

1012
intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv"]

‎source/connect.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ Connect to MongoDB
2424

2525
Create a Client </connect/mongoclient>
2626
Stable API </connect/stable-api>
27+
Choose a Connection Target </connect/connection-targets>
2728
Configure TLS </connect/tls>

‎source/connect/connection-targets.txt

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
.. _ruby-connection-targets:
2+
3+
==========================
4+
Choose a Connection Target
5+
==========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: connection string, URI, server, settings, client
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 a connection string and a ``Mongo::Client`` object
24+
to connect to different types of MongoDB deployments.
25+
26+
Atlas
27+
-----
28+
29+
To connect to a MongoDB deployment on Atlas, include the following elements
30+
in your connection string:
31+
32+
- The URL of your Atlas cluster
33+
- Your MongoDB username
34+
- Your MongoDB password
35+
36+
Then, pass your connection string to the ``Mongo::Client`` constructor.
37+
38+
.. tip::
39+
40+
Follow the :atlas:`Atlas driver connection guide </driver-connection>`
41+
to retrieve your connection string.
42+
43+
When you connect to Atlas, we recommend using the {+stable-api+} client option to avoid
44+
breaking changes when Atlas upgrades to a new version of {+mdb-server+}.
45+
To learn more about the {+stable-api+} feature, see the :ref:`<ruby-stable-api>`
46+
guide.
47+
48+
The following code shows how to use the {+driver-short+} to connect to an Atlas cluster. The
49+
code also uses the ``server_api`` field to specify a {+stable-api+} version.
50+
51+
.. literalinclude:: /includes/connect/connection-targets.rb
52+
:language: ruby
53+
:start-after: start-connection-target-atlas
54+
:end-before: end-connection-target-atlas
55+
:dedent:
56+
57+
Local Deployments
58+
-----------------
59+
60+
To connect to a local standalone MongoDB deployment, specify the host of the
61+
server. Optionally, specify the port of the server and the database to connect
62+
to. If no port is specified, the default port is ``27017``. If no database name
63+
is specified, the client will use the ``admin`` database:
64+
65+
.. literalinclude:: /includes/connect/connection-targets.rb
66+
:language: ruby
67+
:start-after: start-local-connection
68+
:end-before: end-local-connection
69+
:dedent:
70+
71+
You can also specify the host, port, and database to connect to using a
72+
connection string:
73+
74+
.. literalinclude:: /includes/connect/connection-targets.rb
75+
:language: ruby
76+
:start-after: start-local-connection-uri
77+
:end-before: end-local-connection-uri
78+
:dedent:
79+
80+
You can also specify your host as ``localhost``. The following code example
81+
connects to ``localhost`` on the default port, ``27017``:
82+
83+
.. literalinclude:: /includes/connect/connection-targets.rb
84+
:language: ruby
85+
:start-after: start-localhost
86+
:end-before: end-localhost
87+
:dedent:
88+
89+
Replica Sets
90+
------------
91+
92+
To connect to a replica set, it is recommended to specify all nodes that are
93+
part of the replica set. In the event that one or more nodes becomes unavailable,
94+
specifying all nodes allows the driver to still connect to the replica set,
95+
as long as one node is available.
96+
97+
However, it is sufficient to pass the address of any one node in the replica set
98+
to the driver. The node does not have to be the primary, and it may be a hidden node.
99+
The driver will then automatically discover the remaining nodes.
100+
101+
The following example shows how to specify three members of the replica set:
102+
103+
.. literalinclude:: /includes/connect/connection-targets.rb
104+
:language: ruby
105+
:start-after: start-replica-set
106+
:end-before: end-replica-set
107+
:dedent:
108+
109+
The following example shows how to connect to the replica set using a connection
110+
string:
111+
112+
.. literalinclude:: /includes/connect/connection-targets.rb
113+
:language: ruby
114+
:start-after: start-replica-set-uri
115+
:end-before: end-replica-set-uri
116+
:dedent:
117+
118+
The following example shows how to verify the replica set name upon connection
119+
by using the ``replica_set`` option or the ``replicaSet`` connection string option:
120+
121+
.. literalinclude:: /includes/connect/connection-targets.rb
122+
:language: ruby
123+
:start-after: start-replica-set-option
124+
:end-before: end-replica-set-option
125+
:dedent:
126+
127+
API Documentation
128+
-----------------
129+
130+
To learn more about creating a ``Mongo::Client`` object with the {+driver-short+},
131+
see the API documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ .

‎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.

‎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+

0 commit comments

Comments
 (0)