@@ -10,39 +10,98 @@ Write Concern for Replica Sets
1010 :depth: 1
1111 :class: singlecol
1212
13- Write concern describes the level of acknowledgement requested from
14- MongoDB for write operations.
13+ :ref:`Write concern <write-concern>` for replica sets describe the
14+ number of data-bearing members (i.e. the primary and secondaries,
15+ but not arbiters) that must acknowledge a write operation before the
16+ operation returns as successful. A member can only acknowledge a
17+ write operation after it has received and applied the write
18+ successfully.
19+
20+ For replica sets, the default write concern of
21+ :writeconcern:`w: 1 </<number/>>` requires that only the primary
22+ replica set member acknowledge the write before returning
23+ write concern acknowledgment. You can specify an integer
24+ value greater than ``1`` to require acknowledgment from the primary and
25+ as many secondaries as needed to meet the specified value, up to the
26+ total number of data-bearing members in the replica set.
27+
28+ Write operations with a write concern of :writeconcern:`"majority"`
29+ require acknowledgment from a simple majority of data-bearing
30+ voting replica set members (i.e. :rsconf:`members[n].votes` is greater
31+ than ``0`` and :rsconf:`members[n].arbiterOnly` is ``false``). For
32+ clusters where members have :ref:`journaling <journaling-internals>`
33+ enabled, combining ``"majority"`` write concern with
34+ :writeconcern:`j : true <j>` can prevent
35+ :ref:`rollback <replica-set-rollbacks>` of write concern acknowledged
36+ data.
37+
38+ For complete documentation on write acknowledgment
39+ behavior, see :ref:`wc-ack-behavior`.
40+
41+ .. include:: /images/crud-write-concern-w-majority.rst
42+
43+ An application that issues a write operation that requires
44+ write concern acknowledgment waits until the primary receives
45+ acknowledgment from the required number of members for the specified
46+ write concern. For write concern of ``w`` greater than 1 or
47+ ``w : "majority"``, the primary waits until the required number of
48+ secondaries acknowledge the write before returning write concern
49+ acknowledgment. For write concern of ``w: 1``, the primary can return
50+ write concern acknowledgment as soon as it locally applies the write
51+ since it is eligible for contributing to the requested write concern.
52+
53+ The more members that acknowledge a write, the less likely the written
54+ data could roll back if the
55+ :ref:`primary fails <replication-auto-failover>`. However, specifying
56+ a high write concern can increase latency as the client must wait until
57+ it receives the requested level of write concern acknowledgment.
58+
59+ Selecting the ideal write concern for any given write operation depends
60+ on your application's performance goals and data durability
61+ requirements. For more guidance on configuring write concern to
62+ prevent rollbacks, see :ref:`rollback-avoid`.
1563
1664Verify Write Operations to Replica Sets
1765---------------------------------------
1866
19- For a replica set, the default :doc:`write concern
20- </reference/write-concern>` requests acknowledgement only from the primary.
21- You can, however, override this default write concern, such as to
22- confirm write operations on a specified number of the replica set
23- members.
24-
25- .. include:: /images/crud-write-concern-w2.rst
26-
27- To override the default write concern, specify a write concern with
28- each write operation. For example, the following method includes a
29- write concern that specifies that the method return only after the
30- write propagates to the primary and at least one secondary or the
31- method times out after 5 seconds.
67+ The following operation includes the ``writeConcern`` option to
68+ the :method:`~db.collection.insert()` method. The operation specifies
69+ :writeconcern:`"majority"` write concern and a 5 second timeout using
70+ the :ref:`wc-wtimeout` write concern parameter so that the operation
71+ does not block indefinitely.
3272
3373.. code-block:: javascript
3474
3575 db.products.insert(
3676 { item: "envelopes", qty : 100, type: "Clasp" },
37- { writeConcern: { w: 2 , wtimeout: 5000 } }
77+ { writeConcern: { w: "majority" , wtimeout: 5000 } }
3878 )
3979
40- You can include a timeout threshold for a write concern. This prevents
41- write operations from blocking indefinitely if the write concern is
42- unachievable. For example, if the write concern requires
43- acknowledgement from 4 members of the replica set and the replica set
44- has only available 3 members, the operation blocks until those members
45- become available. See :ref:`wc-wtimeout`.
80+ The application waits until the primary returns write concern
81+ acknowledgment, indicating that a simple majority of data-bearing voting
82+ members acknowledged the write operation. For example, in a 3-member
83+ replica set the operation would require acknowledgment from 2 out of
84+ the 3 members. If the replica set was later scaled to include two
85+ additional voting nodes, the same operation would require
86+ acknowledgment from 3 out of the 5 replica set members. If the
87+ primary does not return write concern acknowledgment within the
88+ ``wtimeout`` limit, the write operation fails with a write concern
89+ error.
90+
91+ A write operation that times out waiting for the specified write concern
92+ only indicates that the required number of replica set members did not
93+ acknowledge the write operation within the ``wtimeout`` time period.
94+ It does not necessarily indicate that the primary failed to apply the
95+ write. The data may exist on a subset of replica set nodes at the time
96+ of the write concern error, and can continue replicating until all
97+ nodes in the cluster have that data. Applications should take into
98+ account the potential availability of written data regardless of the
99+ state of write concern acknowledgment.
100+
101+ The exact syntax for specifying write concern depends on the write
102+ operation. Refer to the documentation for the write operation for
103+ instructions on write concern support and syntax. For complete
104+ documentation on write concern, see :ref:`write-concern`.
46105
47106.. seealso::
48107 :ref:`write-methods-incompatibility`
0 commit comments