Navigation

Write Concern

On this page

Write concern describes the level of acknowledgment 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.

Note

For multi-document transactions, you set the write concern at the transaction level, not at the individual operation level. Do not explicitly set the write concern for individual write operations in a transaction.

Starting in MongoDB 4.4, replica sets and sharded clusters support setting a global default write concern. Operations which do not specify an explicit write concern inherit the global default write concern settings. See setDefaultRWConcern for more information.

Write Concern Specification

Write concern can include the following fields:

copy 
{ 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 acknowledgment that the write operation has been written to the on-disk journal, and
  • the wtimeout option to specify a time limit to prevent write operations from blocking indefinitely.

w Option

The w option requests acknowledgment 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 acknowledgment that the write operation has propagated to the specified number of mongod instances. For example:

w: 1
Requests acknowledgment 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. Data can be rolled back if the primary steps down before the write operations have replicated to any of the secondaries.
w: 0

Requests no acknowledgment of the write operation. However, w: 0 may return information about socket exceptions and networking errors to the application. Data can be rolled back if the primary steps down before the write operations have replicated to any of the secondaries.

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

w greater than 1 requires acknowledgment from the primary and as many data-bearing secondaries as needed to meet the specified write concern. For example, consider a 3-member replica set with a primary and 2 secondaries. Specifying w: 2 would require acknowledgment from the primary and one of the secondaries. Specifying w: 3 would require acknowledgment from the primary and both secondaries.

Note

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

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

See Acknowledgment Behavior for when mongod instances acknowledge the write.
"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.

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

See Acknowledgment Behavior for when mongod instances acknowledge the write.
<custom write concern name>

Requests acknowledgment that the write operations have propagated to tagged members that satisfy the custom write concern defined in settings.getLastErrorModes. For an example, see Custom Multi-Datacenter Write Concerns.

Data can be rolled back if the custom write concern only requires acknowledgement from the primary and the primary steps down before the write operations have replicated to any of the secondaries.

See Acknowledgment Behavior for when mongod instances acknowledge the write.

See also

j Option

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

j

If j: true, requests acknowledgment 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.

Note

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.

Acknowledgment Behavior

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

Standalone

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

  j is unspecified j:true j:false
w: 1 In memory On-disk journal In memory
w: "majority" On-disk journal if running with journaling On-disk journal 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 the writes. As such, majority write operations could possibly roll back in the event of a transient loss (e.g. crash and restart) of a majority of nodes in a given replica set.

Replica Sets

The value specified to w determines the number of replica set members that must acknowledge the write before returning success. For each eligible replica set member, the j option determines whether the member acknowledges writes after applying the write operation in memory or after writing to the on-disk journal.

w: "majority"

Any data-bearing voting member of the replica set can contribute to write acknowledgment of "majority" write operations.

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

j is unspecified

Acknowledgment depends on the value of writeConcernMajorityJournalDefault:

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

    writeConcernMajorityJournalDefault defaults to true

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

Note

For behavior details, see w: "majority" Behavior.

w: <number>

Any data-bearing member of the replica set can contribute to write acknowledgment of w: <number> write operations.

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

j is unspecified Acknowledgment requires writing operation in memory (j: false).
j: true Acknowledgment requires writing operation to on-disk journal.
j: false Acknowledgment requires writing operation in memory.

Note

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

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

Additional Information

Causally Consistent Sessions and Write Concerns

With causally consistent client sessions, the client sessions only guarantee causal consistency if:

  • the associated read operations use "majority" read concern, and
  • the associated write operations use "majority" write concern.

For details, see Causal Consistency.

w: "majority" Behavior

  • With writeConcernMajorityJournalDefault set to false, MongoDB does not wait for w: "majority" writes to be written to the on-disk journal before acknowledging the writes. As such, majority write operations could possibly roll back in the event of a transient loss (e.g. crash and restart) of a majority of nodes in a given replica set.
  • 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 MongoDB 4.4, replica set members in the STARTUP2 state do not participate in write majorities.

Calculating Majority for Write Concern

Tip

Starting in version 4.2.1, the rs.status() returns the writeMajorityCount field which contains the calculated majority number.

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).

Write Concern Provenance

Starting in version 4.4, MongoDB tracks write concern provenance, which indicates the source of a particular write concern. You may see provenance shown in the getLastError metrics, write concern error objects, and MongoDB logs.

The following table shows the possible write concern provenance values and their significance:

Provenance Description
clientSupplied The write concern was specified in the application.
customDefault The write concern originated from a custom defined default value. See setDefaultRWConcern.
getLastErrorDefaults The write concern originated from the replica set’s settings.getLastErrorDefaults field.
implicitDefault The write concern originated from the server in absence of all other write concern specifications.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.