-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
read-preference.txt
357 lines (251 loc) · 12.6 KB
/
read-preference.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
.. index:: read preference
.. index:: read preference; background
.. _replica-set-read-preference:
.. _replica-set-read-preference-background:
===============
Read Preference
===============
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
.. include:: /includes/introduction-read-preference.rst
Read preference consists of the :ref:`read preference mode
<read-pref-modes-summary>`, and optionally, a :ref:`tag set
<replica-set-read-preference-tag-sets>` and
:ref:`replica-set-read-preference-max-staleness`.
.. important::
Exercise care when specifying read preferences: Modes other than
:readmode:`primary` may return stale data because with
:ref:`asynchronous replication <asynchronous-replication>`, data in
the secondary may not reflect the most recent write operations.
[#edge-cases-2-primaries]_
.. note:: The read preference does not affect the visibility of data;
i.e. clients can see the results of writes before they are acknowledged
or have propagated to a majority of replica set members. For details,
see :doc:`/core/read-isolation-consistency-recency`.
Use Cases
---------
Indications
~~~~~~~~~~~
The following are common use cases for using non-:readmode:`primary`
read preference modes:
- Running systems operations that do not affect the front-end
application.
.. note::
Read preferences aren't relevant to direct connections to
a single :binary:`~bin.mongod` instance. However, in order to perform
read operations on a direct connection to a secondary member of a
replica set, you must set a read preference, such as
:term:`secondary`.
- Providing local reads for geographically distributed applications.
If you have application servers in multiple data centers, you may
consider having a :ref:`geographically distributed replica set
<replica-set-geographical-distribution>` and using a non primary or
:readmode:`nearest` read preference. This allows the client to read
from the lowest-latency members, rather than always reading from the
primary.
- Maintaining availability during a failover.
Use :readmode:`primaryPreferred` if you want an application to
read from the primary under normal circumstances, but to
allow stale reads from secondaries when the primary is unavailable. This provides a
"read-only mode" for your application during a failover.
Counter-Indications
~~~~~~~~~~~~~~~~~~~
In general, do *not* use :readmode:`secondary` and
:readmode:`secondaryPreferred` to provide extra capacity for
reads, because:
- All members of a replica have roughly equivalent write traffic; as a
result, secondaries will service reads at roughly the same rate as
the primary.
- Replication is asynchronous and there is some amount of
delay between a successful write operation and its replication to
secondaries. Reading from a secondary can return stale data;
reading from different secondaries may result in non-monotonic reads.
.. versionchanged:: 3.6
Starting in MongoDB 3.6, clients can use :ref:`sessions` to ensure
monotonic reads.
- Distributing read operations to secondaries can compromise availability
if *any* members of the set become unavailable because the remaining
members of the set will need to be able to handle all application
requests.
:doc:`Sharding </sharding>` increases read and write capacity by
distributing read and write operations across a group of machines,
and is often a better strategy for adding capacity.
See :doc:`/core/read-preference-mechanics` for more information
about the internal application of read preferences.
.. _read-pref-summary:
.. _read-pref-modes-summary:
Read Preference Modes
---------------------
.. important::
All read preference modes except :readmode:`primary` may return
stale data because :term:`secondaries <secondary>` replicate
operations from the primary with some delay.
[#edge-cases-2-primaries]_ Ensure that your application can tolerate
stale data if you choose to use a non-:readmode:`primary` mode.
.. include:: /includes/read-preference-modes-table.rst
.. index:: tag sets
.. index:: read preference; tag sets
.. _replica-set-read-preference-tag-sets:
Tag Set
-------
If a replica set member or members are associated with
:rsconf:`~members[n].tags`, you can specify a tag set (array of tag
specification documents) in the read preference to target those members.
To :ref:`configure <replica-set-configuration-document>` a member with
tags, set :rsconf:`members[n].tags` to a document that contains the tag
name and value pairs. The value of the tags must be a string.
.. code-block:: javascript
:copyable: false
{ "<tag1>": "<string1>", "<tag2>": "<string2>",... }
Then, you can include a tag set in the read preference to target tagged
members. A tag set is an array of tag specification documents, where
each tag specification document contains one or more tag/value pairs.
.. code-block:: javascript
:copyable: false
[ { "<tag1>": "<string1>", "<tag2>": "<string2>",... }, ... ]
To find replica set members, MongoDB tries each document in succession
until a match is found. See :ref:`read-pref-order-matching` for details.
For example, if a secondary member has the following
:rsconf:`members[n].tags`:
.. code-block:: javascript
{ "region": "South", "datacenter": "A" }
Then, the following tags sets can direct read operations to the aforementioned
secondary (or other members with the same tags):
.. code-block:: javascript
:copyable: false
[ { "region": "South", "datacenter": "A" }, { } ] // Find members with both tag values. If none are found, read from any eligible member.
[ { "region": "South" }, { "datacenter": "A" }, { } ] // Find members with the specified region tag. Only if not found, then find members with the specified datacenter tag. If none are found, read from any eligible member.
[ { "datacenter": "A" }, { "region": "South" }, { } ] // Find members with the specified datacenter tag. Only if not found, then find members with the specified region tag. If none are found, read from any eligible member.
[ { "region": "South" }, { } ] // Find members with the specified region tag value. If none are found, read from any eligible member.
[ { "datacenter": "A" }, { } ] // Find members with the specified datacenter tag value. If none are found, read from any eligible member.
[ { } ] // Find any eligible member.
.. _read-pref-order-matching:
Order of Tag Matching
~~~~~~~~~~~~~~~~~~~~~
If the tag set lists multiple documents, MongoDB tries each document in
succession until a match is found. Once a match is found, that tag
specification document is used to find all eligible matching members,
and the remaining tag specification documents are ignored. If no
members match any of the tag specification documents, the read
operation returns with an error.
.. tip::
To avoid an error if no members match any of the tag specifications,
you can add an empty document ``{ }`` as the last element of the tag
set to read from any eligible member.
For example, consider the following tag set with three tag
specification documents:
.. code-block:: javascript
:copyable: false
[ { "region": "South", "datacenter": "A" }, { "rack": "rack-1" }, { } ]
First, MongoDB tries to find members tagged with both ``"region":
"South"`` and ``"datacenter": "A"``.
.. code-block:: none
:copyable: false
{ "region": "South", "datacenter": "A" }
- If a member is found, the remaining tag specification documents are
not considered. Instead, MongoDB uses this tag specification document
to find all eligible members.
- Else, MongoDB tries to find members with the tags specified in the
second document
.. code-block:: none
:copyable: false
{ "rack": "rack-1" }
- If a member is found tagged, the remaining tag specification
document is not considered. Instead, MongoDB uses this tag
specification document to find all eligible members.
- Else, the third document is considered.
.. code-block:: none
:copyable: false
{ }
The empty document matches any eligible member.
Tag Set and Read Preference Modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tags are not compatible with mode :readmode:`primary`, and in general,
only apply when :ref:`selecting <replica-set-read-preference-behavior-member-selection>`
a :term:`secondary` member of a set for a read operation. However, the
:readmode:`nearest` read mode, when combined with a tag set, selects
the matching member with the lowest network latency. This member may be a
primary or secondary.
.. list-table::
:header-rows: 1
:widths: 20 80
* - Mode
- Notes
* - :readmode:`primaryPreferred`
- Specified tag set only applies if selecting eligible secondaries.
* - :readmode:`secondary`
- Specified tag set always applies.
* - :readmode:`secondaryPreferred`
- Specified tag set only applies if selecting eligible secondaries.
* - :readmode:`nearest`
- Specified tag set applies whether selecting either primary or eligible secondaries.
For information on the interaction between the :ref:`modes
<replica-set-read-preference-modes>` and tag sets, refer to the
:ref:`specific read preference mode documentation
<replica-set-read-preference-modes>`.
For information on configuring tag sets, see the
:doc:`/tutorial/configure-replica-set-tag-sets` tutorial.
Configure Read Preference
-------------------------
When using a MongoDB driver, you can specify the read preference when
:ref:`connecting to the replica set or sharded cluster
<connections-read-preference>`. For example, see :ref:`connection
string <connections-read-preference>`. You can also specify the read
preference at a more granular level. For details, see your driver's
:ecosystem:`api documentation</drivers>`.
For a given read preference, the MongoDB drivers use the same
:ref:`member selection logic
<replica-set-read-preference-behavior-member-selection>`.
When using the :binary:`mongo` shell, see :method:`cursor.readPref()`
and :method:`Mongo.setReadPref()`. For example:
.. code-block:: javascript
db.collection.find({}).readPref( "secondary", [ { "region": "South" } ] )
Read Preference and Transactions
--------------------------------
.. include:: /includes/extracts/transactions-read-pref.rst
.. _replica-set-read-preference-max-staleness:
``maxStalenessSeconds``
-----------------------
.. versionadded:: 3.4
Replica set members can lag behind the :term:`primary` due to network
congestion, low disk throughput, long-running operations, etc. The read
preference ``maxStalenessSeconds`` option lets you specify a maximum
replication lag, or "staleness", for reads from :term:`secondaries
<secondary>`. When a secondary's estimated staleness exceeds
``maxStalenessSeconds``, the client stops using it for read operations.
.. include:: /includes/fact-important-maxStalenessSeconds-intended-use.rst
To use ``maxStalenessSeconds``, all of the
MongoDB instances in your deployment must be using MongoDB 3.4 or
later. If any instances are on an earlier version of MongoDB, the
driver or :binary:`~bin.mongos` will raise an error.
You can specify ``maxStalenessSeconds`` with the following read
preference modes:
- :readmode:`primaryPreferred`
- :readmode:`secondary`
- :readmode:`secondaryPreferred`
- :readmode:`nearest`
Max staleness is not compatible with mode :readmode:`primary` and only
applies when :ref:`selecting
<replica-set-read-preference-behavior-member-selection>` a
:term:`secondary` member of a set for a read operation.
When selecting a server for a read operation with ``maxStalenessSeconds``, clients
estimate how stale each secondary is by comparing the secondary's last
write to that of the primary. The client will then direct the read
operation to a secondary whose estimated lag is less than or equal to
``maxStalenessSeconds``.
If there is no primary, the client uses the secondary with the most
recent write for the comparison.
By default, there is no maximum staleness and clients will not consider a
secondary's lag when choosing where to direct a read operation.
You must specify a ``maxStalenessSeconds`` value of 90 seconds or
longer: specifying a smaller ``maxStalenessSeconds`` value will raise
an error. Clients estimate secondaries' staleness by periodically
checking the latest write date of each replica set member. Since these
checks are infrequent, the staleness estimate is coarse. Thus, clients
cannot enforce a ``maxStalenessSeconds`` value of less than 90 seconds.
.. [#edge-cases-2-primaries]
.. include:: /includes/footnote-two-primaries-edge-cases.rst