Write Concern

Write concern describes the level of acknowledgment requested fromMongoDB for write operations to a standalone mongod orto replica sets or to sharded clusters. In sharded clusters, mongos instances willpass the write concern on to the shards.

Note

For multi-document transactions, you setthe write concern at the transaction level, not at the individualoperation level. Do not explicitly set the write concern forindividual write operations in a transaction.

Write Concern Specification

Write concern can include the following fields:

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

w Option

The w option requests acknowledgment that the write operation haspropagated to a specified number of mongod instances or tomongod instances with specified tags.

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

ValueDescription
- <number>-Requests acknowledgment that the write operation has propagatedto the specified number of mongod instances. Forexample:- w: 1- Requests acknowledgment that the write operation haspropagated to the standalone mongod or the primaryin a replica set. w: 1 is the default write concern forMongoDB.- w: 0-Requests no acknowledgment of the write operation. However, w:0 may return information about socket exceptions andnetworking errors to the application.If you specify w: 0 but include j: true, thej: true prevails to request acknowledgment fromthe standalone mongod or the primary of a replicaset.w greater than 1 requires acknowledgment from the primary andas many additional data-bearing secondaries to meet the specifiedwrite concern. For example, consider a 3-member replica set withno arbiters. Specifying w: 2 wouldrequire acknowledgment from the primary and one of thesecondaries. Specifying w: 3 would require acknowledgmentfrom the primary and both secondaries.NoteHidden,delayed,and priority 0members can acknowledgew: <number> write operations.Delayed secondaries can return write acknowledgment no earlierthan the configured slaveDelay.See Acknowledgment Behavior for when mongod instancesacknowledge the write.
- "majority"-Requests acknowledgment that write operations have propagated tothe majority(M) of data-bearing voting members. The majority (M) iscalculated as the majority of all voting members[1], but the write operation returnsacknowledgement after propagating to M-number of data-bearingvoting members (primary and secondaries withmembers[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, Mis two [1], and the write must propagateto the primary and one secondary to acknowledge thewrite concern to the client.Starting in version 4.2.1, the rs.status() returnswriteMajorityCount.NoteHidden,delayed,and priority 0members with members[n].votes greater than 0can acknowledge "majority" write operations.Delayed secondaries can return write acknowledgment no earlierthan the configured slaveDelay.After the write operation returns with a w:"majority" acknowledgment to the client, theclient can read the result of that write with a"majority" readConcern.See Acknowledgment Behavior for when mongod instancesacknowledge the write.
- <custom write concern name>-Requests acknowledgment that the write operations havepropagated to tagged members thatsatisfy the custom write concern defined insettings.getLastErrorModes.For an example, see Custom Multi-Datacenter Write Concerns.See Acknowledgment Behavior for when mongodinstances acknowledge the write.

See also

Replica Set Protocol Version

j Option

The j option requests acknowledgment from MongoDB thatthe write operation has been written to the on-disk journal.

- j-If j: true, requests acknowledgment that themongod 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 berolled back due to replica set primary failover.Changed in version 3.2: With j: true, MongoDB returns only after therequested number of members, including the primary, have written to thejournal. Previously j: true write concern in areplica set only requires the primary to write to the journal,regardless of the w: <value> write concern.

Note

wtimeout

This option specifies a time limit, in milliseconds, for the writeconcern. wtimeout is only applicable for w values greater than1.

wtimeout causes write operations to return with an errorafter the specified limit, even if the required write concern willeventually succeed. When these write operations return,MongoDB does not undo successful data modifications performedbefore the write concern exceeded the wtimeout time limit.

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

Acknowledgment Behavior

The w option and the j option determinewhen mongod instances acknowledge write operations.

Standalone

A standalone mongod acknowledges a write operation eitherafter applying the write in memory or after writing to the on-diskjournal. The following table lists the acknowledgment behavior for astandalone and the relevant write concerns:

j is unspecifiedj:truej:false
w: 1In memoryOn-disk journalIn memory
w: "majority"On-disk journal if running with journalingOn-disk journalIn memory

Note

With writeConcernMajorityJournalDefault set to false,MongoDB does not wait for w: "majority"writes to be written to the on-disk journal before acknowledging thewrites. As such, majority write operations couldpossibly roll back in the event of a transient loss (e.g. crash andrestart) of a majority of nodes in a given replica set.

Replica Sets

The value specified to w determines the numberof replica set members that must acknowledge the write before returningsuccess. For each eligible replica set member, the joption determines whether the member acknowledges writes after applyingthe write operation in memory or after writing to the on-disk journal.

  • w: "majority"
  • Any data-bearing voting member of the replica set can contributeto write acknowledgment of "majority" writeoperations.

The following table lists when the member can acknowledgethe write based on the j value:

j is unspecifiedAcknowledgment depends on the value ofwriteConcernMajorityJournalDefault:

  • If true, acknowledgment requires writing operation toon-disk journal (j: true).

writeConcernMajorityJournalDefault defaults totrue

  • If false, acknowledgment requires writing operation inmemory (j: false).j: trueAcknowledgment requires writing operation to on-disk journal.j: falseAcknowledgment requires writing operation in memory.

Note

With writeConcernMajorityJournalDefault set to false,MongoDB does not wait for w: "majority"writes to be written to the on-disk journal before acknowledging thewrites. As such, majority write operations couldpossibly roll back in the event of a transient loss (e.g. crash andrestart) of a majority of nodes in a given replica set.

Note

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

Delayed secondaries can return write acknowledgment no earlierthan the configured slaveDelay.

  • w: <number>
  • Any data-bearing member of the replica set can contributeto write acknowledgment of w: writeoperations.

The following table lists when the member can acknowledgethe write based on the j value:

j is unspecifiedAcknowledgment requires writing operation in memory(j: false).j: trueAcknowledgment requires writing operation to on-disk journal.j: falseAcknowledgment requires writing operation in memory.

Note

Hidden,delayed,and priority 0members can acknowledgew: <number> write operations.

Delayed secondaries can return write acknowledgment no earlierthan the configured slaveDelay.

[1](1, 2) The majority (M) is calculated as the majority of all votingmembers. As such, even if a replica setwith 3 voting members is a Primary-Secondary-Arbiter (P-S-A), themajority (M) is two. However, since the write can only beapplied to data-bearing members, the write must propagate to theprimary and the secondary to acknowledge the write concern to theclient.