Navigation
This version of the documentation is archived and no longer supported.

Write Concern

Write concern describes the level of acknowledgement requested from MongoDB for write operations to a standalone mongod or to replica sets or to sharded clusters. In sharded clusters, mongos instances will pass the write concern on to the shards.

Changed in version 2.6: A new protocol for write operations integrates write concerns with the write operations and eliminates the need to call the getLastError command. Previous versions required a getLastError command immediately after a write operation to specify the write concern.

Write Concern Specification

Write concern can include the following fields:

{ w: <value>, j: <boolean>, wtimeout: <number> }
  • the w option to request acknowledgment that the write operation has propagated to a specified number of mongod instances or to mongod instances with specified tags.
  • the j option to request acknowledgement that the write operation has been written to the journal, and
  • wtimeout option to specify a time limit to prevent write operations from blocking indefinitely.

w Option

The w option requests acknowledgement that the write operation has propagated to a specified number of mongod instances or to mongod instances with specified tags.

Using the w option, the following w: <value> write concerns are available:

Value Description
<number>

Requests acknowledgement that the write operation has propagated to the specified number of mongod instances. For example:

w: 1
Requests acknowledgement that the write operation has propagated to the standalone mongod or the primary in a replica set. w: 1 is the default write concern for MongoDB.
w: 0

Requests no acknowledgment of the write operation. However, w: 0 may return information about socket exceptions and networking errors to the application.

If you specify w: 0 but include j: true, the j: true prevails to request acknowledgement from the standalone mongod or the primary of a replica set.

Numbers greater than 1 are valid only for replica sets to request acknowledgement from specified number of members, including the primary.

"majority"

Requests acknowledgment that write operations have propagated to the calculated majority of the data-bearing voting members (i.e. primary and secondaries with members[n].votes greater than 0).

For example, consider a replica set with 3 voting members, Primary-Secondary-Secondary (P-S-S). For this replica set, calculated majority is two, and the write must propagate to the primary and one secondary to acknowledge the write concern to the client.

Note

Hidden, delayed, and priority 0 members with members[n].votes greater than 0 can acknowledge "majority" write operations.

Delayed secondaries can return write acknowledgment no earlier than the configured slaveDelay.

Starting in version 3.2.6
For replica sets using protocolVersion: 1, w: "majority" may imply j: true if journaling is enabled. See writeConcernMajorityJournalDefault.
In earlier 3.2 versions,
w: "majority" implies j: true if journaling is enabled. With earlier versions of MongoDB, w: "majority" does not imply journaling.

After the write operation returns with a w: "majority" acknowledgement to the client, the client can read the result of that write with a "majority" readConcern.

<tag set>
Requests acknowledgement that the write operations have propagated to a replica set member with the specified tag.

j Option

The j option requests acknowledgement from MongoDB that the write operation has been written to the journal.

j

Requests acknowledgement that the mongod instances, as specified in the w: <value>, have written to the on-disk journal. j: true does not by itself guarantee that the write will not be rolled back due to replica set primary failover.

Changed in version 3.2: With j: true, MongoDB returns only after the requested number of members, including the primary, have written to the journal. Previously j: true write concern in a replica set only requires the primary to write to the journal, regardless of the w: <value> write concern.

Changed in version 2.6: Specifying a write concern that includes j: true to a mongod or mongos running with --nojournal option produces an error. Previous versions would ignore the j: true.

wtimeout

This option specifies a time limit, in milliseconds, for the write concern. wtimeout is only applicable for w values greater than 1.

wtimeout causes write operations to return with an error after the specified limit, even if the required write concern will eventually succeed. When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the wtimeout time limit.

If you do not specify the wtimeout option and the level of write concern is unachievable, the write operation will block indefinitely. Specifying a wtimeout value of 0 is equivalent to a write concern without the wtimeout option.

Acknowlegement Behavior

Calculating Majority for Write Concern

The majority for write concern "majority" is calculated as the smaller of the following values:

  • the majority of all voting members (including arbiters) vs.
  • the number of all data-bearing voting members.

Warning

In cases where the calculated majority number is equal to the number of all data-bearing voting members (such as with a 3-member Primary-Secondary-Arbiter deployment), write concern "majority" may time out or never be acknowledged if a data bearing voting member is down or unreachable. If possible, use a data-bearing voting member instead of an arbiter.

For example, consider:

  • A replica set with 3 voting members, Primary-Secondary-Secondary (P-S-S):

    • The majority of all voting members is 2.
    • The number of all data-bearing voting members is 3.
    The calculated majority is 2, the minimum of 2 and 3. The write must propagate to the primary and one of the secondaries to acknowledge the write concern "majority" to the client.
  • A replica set with 3 voting members, Primary-Secondary-Arbiter (P-S-A)

    • The majority of all voting members is 2.
    • The number of all data-bearing voting members is 2.
    The calculated majority is 2, the minimum of 2 and 2. Since the write can only be applied to data-bearing members, the write must propagate to the primary and the secondary to acknowledge the write concern "majority" to the client.

    Tip

    Avoid using a "majority" write concern with a (P-S-A) or other topologies that require all data-bearing voting members to be available to acknowledge the writes. Customers who want the durability guarantees of using a "majority" write concern should instead deploy a topology that does not require all data bearing voting members to be available (e.g. P-S-S).