Skip to content

Commit 9419901

Browse files
lindseymoorelindseymoore
authored
DOCSP-42104 CSOT (#136)
* first draft * revisions * edit * edits * code edits * Rea comments * edits * last internal comments * tech review + add atlas search api refs * edit to api refs * code comment edit * fix code example option name
1 parent b7e219d commit 9419901

File tree

4 files changed

+279
-0
lines changed

4 files changed

+279
-0
lines changed

‎source/connect.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,4 @@ Connect to MongoDB
2727
Choose a Connection Target </connect/connection-targets>
2828
Connection Options </connect/connection-options>
2929
Configure TLS </connect/tls>
30+
Limit Server Execution Time </connect/csot>

‎source/connect/csot.txt

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
.. _ruby-csot:
2+
3+
===========================
4+
Limit Server Execution Time
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: error, blocking, thread, task, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the ``timeout_ms`` option to set a
24+
timeout for server operations.
25+
26+
When you use the {+driver-short+} to perform a server operation, you can
27+
limit the duration allowed for the server to finish the operation. To do so,
28+
specify a **client-side operation timeout (CSOT)**. The timeout applies to all
29+
steps needed to complete the operation, including server selection, connection
30+
checkout, and server-side execution. If the timeout expires before the operation
31+
completes, the {+driver-short+} raises a timeout exception.
32+
33+
timeout_ms Option
34+
-----------------
35+
36+
To specify a timeout when connecting to a MongoDB deployment, set the
37+
``timeout_ms`` connection option to the timeout length in milliseconds. You can
38+
specify a timeout value in the following ways:
39+
40+
- Pass the ``timeout_ms`` client option to the ``Mongo::Client`` constructor.
41+
- Pass the ``timeoutMS`` connection string option as a parameter to your connection string.
42+
43+
Select from the following tabs to view examples for how to use the ``timeout_ms`` client
44+
option or the ``timeoutMS`` connection string option to specify a timeout of 30 seconds:
45+
46+
.. tabs::
47+
48+
.. tab:: Mongo::Client
49+
:tabid: mongoclient
50+
51+
.. code-block:: ruby
52+
:emphasize-lines: 2
53+
54+
uri = "<connection string>"
55+
options = { timeout_ms: 30000 }
56+
57+
client = Mongo::Client.new(uri, options)
58+
59+
.. tab:: Connection String
60+
:tabid: connection-string
61+
62+
.. code-block:: ruby
63+
:emphasize-lines: 1
64+
65+
uri = "mongodb://<hostname>:<port>?timeoutMS=30000"
66+
client = Mongo::Client.new(uri)
67+
68+
If you specify the ``timeout_ms`` option, the driver automatically applies the
69+
specified timeout for each server operation.
70+
71+
.. note::
72+
73+
The ``timeout_ms`` connection option unifies most timeout related options.
74+
The following timeout options are deprecated:
75+
76+
- ``socket_timeout``
77+
- ``wait_queue_timeout``
78+
- ``wtimeout``
79+
- ``max_time_ms``
80+
- ``max_commit_time_ms``
81+
82+
The ``timeout_ms`` connection option takes precedence over these
83+
deprecated timeout options.
84+
85+
Timeout Inheritance
86+
~~~~~~~~~~~~~~~~~~~
87+
88+
When you specify a ``timeout_ms`` option, the driver applies the timeout
89+
according to the same inheritance behaviors as the other {+driver-short+} options.
90+
The following table describes how the timeout value is inherited at each level:
91+
92+
.. list-table::
93+
:header-rows: 1
94+
:widths: 30 70
95+
96+
* - Level
97+
- Inheritance Description
98+
99+
* - Operation
100+
- Takes the highest precedence and overrides ``timeout_ms``
101+
options set at any other level.
102+
103+
* - Transaction
104+
- Takes precedence over ``timeout_ms`` set at the session,
105+
collection, database, or client level.
106+
107+
* - Session
108+
- Applies to all transactions and operations within
109+
that session, unless the option is overridden by options set at those levels.
110+
111+
* - Database
112+
- Applies to all sessions and operations within that
113+
database, unless the option is overridden by options set at those levels.
114+
115+
* - Collection
116+
- Applies to all sessions and operations on that
117+
collection, unless the option is overridden by options set at those levels.
118+
119+
* - Client
120+
- Applies to all databases, collections, sessions, transactions, and
121+
operations within that client that do not otherwise specify
122+
``timeout_ms``.
123+
124+
To learn more about overriding the timeout option and setting other options, see the
125+
following :ref:`ruby-csot-overrides` section.
126+
127+
.. _ruby-csot-overrides:
128+
129+
Overrides
130+
---------
131+
132+
You can specify a ``timeout_ms`` option at the operation level to override the
133+
client-level configuration for a specific operation. This allows you to
134+
customize timeouts based on the needs of individual queries.
135+
136+
The following example demonstrates how an operation-level ``timeout_ms``
137+
configuration can override a client-level ``timeout_ms`` configuration:
138+
139+
.. literalinclude:: /includes/connect/csot.rb
140+
:language: ruby
141+
:start-after: start-csot-overrides
142+
:end-before: end-csot-overrides
143+
144+
Transactions
145+
~~~~~~~~~~~~
146+
147+
You can set a timeout for transactions by using the ``default_timeout_ms`` client option.
148+
149+
When you create a new ``Mongo::Session`` instance to implement a transaction,
150+
you can set the ``default_timeout_ms`` client option to specify the
151+
``timeout_ms`` values for the following methods:
152+
153+
- `commit_transaction <{+api-root+}/Mongo/Session.html#commit_transaction-instance_method>`__
154+
- `abort_transaction <{+api-root+}/Mongo/Session.html#abort_transaction-instance_method>`__
155+
- `with_transaction <{+api-root+}/Mongo/Session.html#with_transaction-instance_method>`__
156+
- `end_session <{+api-root+}/Mongo/Session.html#end_session-instance_method>`__
157+
158+
If you do not specify ``default_timeout_ms``, the driver uses the ``timeout_ms``
159+
value set on the parent ``Mongo::Client``.
160+
161+
You cannot override the ``timeout_ms`` value of the ``Mongo::Client`` for a
162+
call to ``start_session``.
163+
164+
You can only set a timeout value for the
165+
`start_transaction <{+api-root+}/Mongo/Session.html#start_transaction-instance_method>`__
166+
method by using the ``timeout_ms`` option.
167+
168+
You cannot override ``default_timeout_ms`` by setting the ``timeout_ms`` option on an
169+
operation in a transaction session provided by the ``with_transaction`` callback,
170+
or the driver throws an error.
171+
172+
Client Encryption
173+
~~~~~~~~~~~~~~~~~
174+
175+
When you use Client-Side Field Level Encryption (CSFLE), the driver uses the
176+
``timeout_ms`` option to limit the time allowed for encryption and decryption
177+
operations.
178+
179+
If you specify the ``timeout_ms`` option when you construct a
180+
``ClientEncryption`` instance, it controls the lifetime of all operations
181+
performed on that instance. If you do not provide ``timeout_ms``, the instance
182+
inherits the ``timeout_ms`` setting from the ``Mongo::Client`` used in the
183+
``ClientEncryption`` constructor.
184+
185+
If you set ``timeout_ms`` on both the client and directly in
186+
``ClientEncryption``, the value provided to ``ClientEncryption`` takes
187+
precedence.
188+
189+
Cursors
190+
-------
191+
192+
Cursors offer configurable timeout settings when using the CSOT feature. You can
193+
adjust cursor handling by configuring either the cursor lifetime or cursor
194+
iteration mode if needed. To configure the mode, set the ``timeoutMode`` option
195+
to ``cursorLifetime``, which is the default, or ``iteration``.
196+
197+
Cursor Lifetime Mode
198+
~~~~~~~~~~~~~~~~~~~~
199+
200+
The cursor lifetime mode uses ``timeout_ms`` to limit the entire lifetime of a
201+
cursor. In this mode, the initialization of the cursor and all subsequent calls
202+
to the cursor methods must complete within the limit specified by the
203+
``timeout_ms`` option. All documents must be returned within this limit.
204+
Otherwise, the cursor's lifetime expires and a timeout error occurs.
205+
206+
When you close a cursor by calling the ``to_a`` or ``close`` method, the
207+
timeout resets to ensure server-side resources are cleaned up.
208+
209+
The following example shows how to set the ``timeout_ms`` option to ensure that
210+
the cursor is initialized and all documents are retrieved within 10 seconds:
211+
212+
.. code-block:: ruby
213+
214+
docs = collection.find({}, timeout_ms:10000).to_a
215+
216+
Cursor Iteration Mode
217+
~~~~~~~~~~~~~~~~~~~~~
218+
219+
The cursor iteration mode uses the ``timeout_ms`` option to limit each call to
220+
the ``try_next`` method. The timeout refreshes after each call completes.
221+
This is the default mode for all tailable cursors,
222+
such as the tailable cursors returned by the ``find`` method on capped
223+
collections or change streams.
224+
225+
The following code example iterates over documents in a sample collection
226+
by using an iterable cursor, and then fetches and logs the ``title`` information for
227+
each movie document:
228+
229+
.. literalinclude:: /includes/connect/csot.rb
230+
:language: ruby
231+
:start-after: start-csot-iterable
232+
:end-before: end-csot-iterable
233+
234+
API Documentation
235+
-----------------
236+
237+
To learn more about using timeouts with the {+driver-short+}, see the following
238+
API documentation:
239+
240+
- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__
241+
- `Mongo::Session <{+api-root+}/Mongo/Session.html>`__

‎source/includes/connect/csot.rb

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# start-csot-overrides
2+
require 'mongo'
3+
4+
# Replace the placeholder with your connection string
5+
uri = "<connection string>"
6+
7+
# Sets a client-level timeout configuration
8+
options = { timeout_ms: 30000 }
9+
10+
Mongo::Client.new(uri, options) do |client|
11+
db = client.use('test-db')
12+
collection = db[:test-collection]
13+
14+
# Performs a query with an operation-level timeout configuration,
15+
# overriding the client-level configuration
16+
docs = collection.find({}, timeout_ms: 10000).to_a
17+
18+
docs.each { |doc| puts doc }
19+
end
20+
# end-csot-overrides
21+
22+
# start-csot-iterable
23+
cursor = collection.find()
24+
25+
cursor.each do |movie|
26+
puts movie['title']
27+
end
28+
# end-csot-iterable

‎source/indexes/atlas-search-index.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,3 +119,12 @@ Additional Information
119119

120120
To learn more about MongoDB Atlas Search, see the
121121
:atlas:`Atlas Search </atlas-search/atlas-search-overview/>` documentation.
122+
123+
API Documentation
124+
~~~~~~~~~~~~~~~~~
125+
126+
To learn more about any of the methods discussed in this guide, see the
127+
following API documentation:
128+
129+
- `search_indexes <{+api-root+}/Mongo/Collection.html#search_indexes-instance_method>`__
130+
- `SearchIndex <{+api-root+}/Mongo/SearchIndex/View.html>`__

0 commit comments

Comments
 (0)