Skip to content

Commit 46de623

Browse files
mongoKartmongoKart
committed
wip
1 parent 9e0d576 commit 46de623

File tree

3 files changed

+161
-142
lines changed

3 files changed

+161
-142
lines changed

‎source/crud.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ CRUD Operations
2828
Delete Documents </delete>
2929
Bulk Write Operations </write/bulk-write>
3030
Transactions </write/transactions>
31-
text search
32-
configure
31+
32+
configure CRUD
3333
retryable reads
3434
retryable writes
3535
Store Large Files </write/gridfs>

‎source/crud/configure.txt

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. _pymongo-configure-crud:
2+
.. _pymongo-config-read-write:
3+
4+
=========================
5+
Configure CRUD Operations
6+
=========================
7+
8+
.. contents:: On this page
9+
:local:
10+
:backlinks: none
11+
:depth: 2
12+
:class: singlecol
13+
14+
.. facet::
15+
:name: genre
16+
:values: reference
17+
18+
.. meta::
19+
:keywords: insert, update, replace, delete, options, code example
20+
21+
Overview
22+
--------
23+
24+
In this guide, you can learn how to configure read and write operations in {+driver-short+}.
25+
26+
You can control how the driver routes read operations by setting a **read preference**.
27+
You can also control options for how the driver waits for acknowledgment of
28+
read and write operations on a replica set by setting a **read concern** and a
29+
**write concern**.
30+
31+
By default, databases inherit these settings from the ``MongoClient`` instance,
32+
and collections inherit them from the database. However, you can change these
33+
settings on your database or collection by using one of the following methods:
34+
35+
- ``get_database()``: Gets the database and applies the client's read
36+
preference, read concern, and write preference.
37+
- ``database.with_options()``: Gets the database and applies its current read
38+
preference, read concern, and write preference.
39+
- ``get_collection()``: Gets the collection and applies its current read preference, read concern, and write preference.
40+
- ``collection.with_options()``: Gets the collection and applies the database's read
41+
preference, read concern, and write preference.
42+
43+
To change read or write settings with the preceding methods, call the method and
44+
pass in the collection or database name, and the new read preference, read
45+
concern, or write preference.
46+
47+
The following example shows how to change the read preference, read concern and
48+
write preference of a database called ``test-database`` with the ``get_database()`` method:
49+
50+
.. code-block:: python
51+
52+
client.get_database("test-database",
53+
read_preference=ReadPreference.SECONDARY,
54+
read_concern="local",
55+
write_concern="majority")
56+
57+
The following example shows how to change read and write settings of a
58+
collection called ``test-collection`` with the ``get_collection()`` method:
59+
60+
.. code-block:: python
61+
62+
database.get_collection("test-collection",
63+
read_preference=ReadPreference.SECONDARY,
64+
read_concern="local",
65+
write_concern="majority")
66+
67+
The following example shows how to change read and write settings of a
68+
collection called ``test-collection`` with the ``with_options()`` method:
69+
70+
.. code-block:: python
71+
72+
collection.with_options(read_preference=ReadPreference.SECONDARY,
73+
read_concern="local",
74+
write_concern="majority")
75+
76+
.. tip::
77+
78+
To see the types of read preferences available in the ``ReadPreference`` enum, see the
79+
`API documentation <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference>`__.
80+
81+
To learn more about the read and write settings, see the following guides in the
82+
MongoDB Server manual:
83+
84+
- :manual:`Read Preference </core/read-preference/>`
85+
- :manual:`Read Concern </reference/read-concern/>`
86+
- :manual:`Write Concern </reference/write-concern/>`
87+
88+
Tag Sets
89+
~~~~~~~~
90+
91+
In {+mdb-server+}, you can apply key-value :manual:`tags
92+
</core/read-preference-tags/>` to replica-set
93+
members according to any criteria you choose. You can then use
94+
those tags to target one or more members for a read operation.
95+
96+
By default, {+driver-short+} ignores tags
97+
when choosing a member to read from. To instruct {+driver-short+}
98+
to prefer certain tags, pass them as a parameter to your
99+
`read preference class <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.Primary>`__
100+
constructor.
101+
102+
In the following code example, the tag set passed to the ``read_preference`` parameter
103+
instructs {+driver-short+} to prefer reads from the
104+
New York data center (``'dc': 'ny'``) and to fall back to the San Francisco data
105+
center (``'dc': 'sf'``):
106+
107+
.. code-block:: python
108+
109+
db = client.get_database(
110+
'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}]))
111+
112+
Local Threshold
113+
~~~~~~~~~~~~~~~
114+
115+
If multiple replica-set members match the read preference and tag sets you specify,
116+
{+driver-short+} reads from the nearest replica-set members, chosen according to
117+
their ping time.
118+
119+
By default, the driver uses only those members whose ping times are within 15 milliseconds
120+
of the nearest member for queries. To distribute reads between members with
121+
higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor.
122+
123+
The following example specifies a local threshold of 35 milliseconds:
124+
125+
.. code-block:: python
126+
:emphasize-lines: 3
127+
128+
client = MongoClient(replicaSet='repl0',
129+
readPreference=ReadPreference.SECONDARY_PREFERRED,
130+
localThresholdMS=35)
131+
132+
In the preceding example, {+driver-short+} distributes reads between matching members
133+
within 35 milliseconds of the closest member's ping time.
134+
135+
.. note::
136+
137+
{+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a
138+
replica set through a ``mongos`` instance. In this case, use the
139+
:manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
140+
command-line option.
141+
142+
Retryable Reads and Writes
143+
~~~~~~~~~~~~~~~~~~~~~~~~~~
144+
145+
{+driver-short+} automatically retries certain read and write operations a single time
146+
if they fail due to a network or server error.
147+
148+
You can explicitly disable retryable reads or retryable writes by setting the ``retryReads`` or
149+
``retryWrites`` option to ``False`` in the ``MongoClient()`` constructor. The following
150+
example disables retryable reads and writes for a client:
151+
152+
.. code-block:: python
153+
154+
client = MongoClient("<connection string>",
155+
retryReads=False, retryWrites=False)
156+
157+
To learn more about supported retryable read operations, see :manual:`Retryable Reads </core/retryable-reads/>`
158+
in the {+mdb-server+} manual. To learn more about supported retryable write
159+
operations, see :manual:`Retryable Writes </core/retryable-writes/>` in the {+mdb-server+} manual.

‎source/databases-collections.txt

Lines changed: 0 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -181,146 +181,6 @@ The following example deletes the ``test_collection`` collection:
181181

182182
Drop a collection only if the data in it is no longer needed.
183183

184-
.. _pymongo-config-read-write:
185-
186-
Configure Read and Write Operations
187-
-----------------------------------
188-
189-
You can control how the driver routes read operations by setting a **read preference**.
190-
You can also control options for how the driver waits for acknowledgment of
191-
read and write operations on a replica set by setting a **read concern** and a
192-
**write concern**.
193-
194-
By default, databases inherit these settings from the ``MongoClient`` instance,
195-
and collections inherit them from the database. However, you can change these
196-
settings on your database or collection by using one of the following methods:
197-
198-
- ``get_database()``: Gets the database and applies the client's read
199-
preference, read concern, and write preference.
200-
- ``database.with_options()``: Gets the database and applies its current read
201-
preference, read concern, and write preference.
202-
- ``get_collection()``: Gets the collection and applies its current read preference, read concern, and write preference.
203-
- ``collection.with_options()``: Gets the collection and applies the database's read
204-
preference, read concern, and write preference.
205-
206-
To change read or write settings with the preceding methods, call the method and
207-
pass in the collection or database name, and the new read preference, read
208-
concern, or write preference.
209-
210-
The following example shows how to change the read preference, read concern and
211-
write preference of a database called ``test-database`` with the ``get_database()`` method:
212-
213-
.. code-block:: python
214-
215-
client.get_database("test-database",
216-
read_preference=ReadPreference.SECONDARY,
217-
read_concern="local",
218-
write_concern="majority")
219-
220-
The following example shows how to change read and write settings of a
221-
collection called ``test-collection`` with the ``get_collection()`` method:
222-
223-
.. code-block:: python
224-
225-
database.get_collection("test-collection",
226-
read_preference=ReadPreference.SECONDARY,
227-
read_concern="local",
228-
write_concern="majority")
229-
230-
The following example shows how to change read and write settings of a
231-
collection called ``test-collection`` with the ``with_options()`` method:
232-
233-
.. code-block:: python
234-
235-
collection.with_options(read_preference=ReadPreference.SECONDARY,
236-
read_concern="local",
237-
write_concern="majority")
238-
239-
.. tip::
240-
241-
To see the types of read preferences available in the ``ReadPreference`` enum, see the
242-
`API documentation <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference>`__.
243-
244-
To learn more about the read and write settings, see the following guides in the
245-
MongoDB Server manual:
246-
247-
- :manual:`Read Preference </core/read-preference/>`
248-
- :manual:`Read Concern </reference/read-concern/>`
249-
- :manual:`Write Concern </reference/write-concern/>`
250-
251-
Tag Sets
252-
~~~~~~~~
253-
254-
In {+mdb-server+}, you can apply key-value :manual:`tags
255-
</core/read-preference-tags/>` to replica-set
256-
members according to any criteria you choose. You can then use
257-
those tags to target one or more members for a read operation.
258-
259-
By default, {+driver-short+} ignores tags
260-
when choosing a member to read from. To instruct {+driver-short+}
261-
to prefer certain tags, pass them as a parameter to your
262-
`read preference class <{+api-root+}pymongo/read_preferences.html#pymongo.read_preferences.Primary>`__
263-
constructor.
264-
265-
In the following code example, the tag set passed to the ``read_preference`` parameter
266-
instructs {+driver-short+} to prefer reads from the
267-
New York data center (``'dc': 'ny'``) and to fall back to the San Francisco data
268-
center (``'dc': 'sf'``):
269-
270-
.. code-block:: python
271-
272-
db = client.get_database(
273-
'test', read_preference=Secondary([{'dc': 'ny'}, {'dc': 'sf'}]))
274-
275-
Local Threshold
276-
~~~~~~~~~~~~~~~
277-
278-
If multiple replica-set members match the read preference and tag sets you specify,
279-
{+driver-short+} reads from the nearest replica-set members, chosen according to
280-
their ping time.
281-
282-
By default, the driver uses only those members whose ping times are within 15 milliseconds
283-
of the nearest member for queries. To distribute reads between members with
284-
higher latencies, pass the ``localThresholdMS`` option to the ``MongoClient()`` constructor.
285-
286-
The following example specifies a local threshold of 35 milliseconds:
287-
288-
.. code-block:: python
289-
:emphasize-lines: 3
290-
291-
client = MongoClient(replicaSet='repl0',
292-
readPreference=ReadPreference.SECONDARY_PREFERRED,
293-
localThresholdMS=35)
294-
295-
In the preceding example, {+driver-short+} distributes reads between matching members
296-
within 35 milliseconds of the closest member's ping time.
297-
298-
.. note::
299-
300-
{+driver-short+} ignores the value of ``localThresholdMS`` when communicating with a
301-
replica set through a ``mongos`` instance. In this case, use the
302-
:manual:`localThreshold </reference/program/mongos/#std-option-mongos.--localThreshold>`
303-
command-line option.
304-
305-
Retryable Reads and Writes
306-
~~~~~~~~~~~~~~~~~~~~~~~~~~
307-
308-
{+driver-short+} automatically retries certain read and write operations a single time
309-
if they fail due to a network or server error.
310-
311-
You can explicitly disable retryable reads or retryable writes by setting the ``retryReads`` or
312-
``retryWrites`` option to ``False`` in the ``MongoClient()`` constructor. The following
313-
example disables retryable reads and writes for a client:
314-
315-
.. code-block:: python
316-
317-
client = MongoClient("<connection string>",
318-
retryReads=False, retryWrites=False)
319-
320-
To learn more about supported retryable read operations, see :manual:`Retryable Reads </core/retryable-reads/>`
321-
in the {+mdb-server+} manual. To learn more about supported retryable write
322-
operations, see :manual:`Retryable Writes </core/retryable-writes/>` in the {+mdb-server+} manual.
323-
324184
Troubleshooting
325185
---------------
326186

0 commit comments

Comments
 (0)