Write Concern (original) (raw)

Write concern describes the level of acknowledgment requested from MongoDB for write operations to a standalone mongod,replica sets, or sharded clusters. In sharded clusters, mongosinstances 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.

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.

To learn more about setting the write concern for deployments hosted in MongoDB Atlas, seeBuild a Resilient Application with MongoDB Atlas

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

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. If the write concern is missing the w field, MongoDB sets the w option to the default write concern.

Note

If you use the setDefaultRWConcern to set the default write concern, you must specify a w field value.

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

See also:

• Default MongoDB Read Concerns/Write Concerns
• Self-Managed Replica Set Protocol Version

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

Note

• Specifying a write concern that includes j: true to amongod instance that is running without journaling produces an error.
• If journaling is enabled, w: "majority" may imply j: true. ThewriteConcernMajorityJournalDefault replica set configuration setting determines the behavior. SeeAcknowledgment Behavior for details.
• A write concern that includes or implies j: true causes an immediate journal synchronization. See Journaling Process.

This option specifies a time limit, in milliseconds, for a write operation to propagate to enough members to achieve the write concern after the operation succeeds on the primary. If w is less than or equal to 1, wtimeoutdoes not apply. If the write operation doesn't achieve the write concern within this time limit, MongoDB returns a write concern error.

wtimeout causes write operations to return with a write concern 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.

Note

To set a time limit on the primary write operation, use themaxTimeMS() method.

Starting in MongoDB 5.0, the implicit defaultwrite concern isw: majority. However, special considerations are made for deployments containingarbiters:

• The voting majority of a replica set is 1 plus half the number of voting members, rounded down. If the number of data-bearing voting members is not greater than the voting majority, the default write concern is { w: 1 }.
• In all other scenarios, the default write concern is { w: "majority" }.

Specifically, MongoDB uses the following formula to determine the default write concern:

if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ]

    defaultWriteConcern = { w: 1 }

else

    defaultWriteConcern = { w: "majority" }

For example, consider the following deployments and their respective default write concerns:

• In the first example:
  • There are 2 non-arbiters and 1 arbiter for a total of 3 voting nodes.
  • The majority of voting nodes (1 plus half of 3, rounded down) is 2.
  • The number of non-arbiters (2) is equal to the majority of voting nodes (2), resulting in an implicit write concern of { w: 1 }.
• In the second example:
  • There are 4 non-arbiters and 1 arbiter for a total of 5 voting nodes.
  • The majority of voting nodes (1 plus half of 5, rounded down) is 3.
  • The number of non-arbiters (4) is greater than the majority of voting nodes (3), resulting in an implicit write concern of{ w: "majority" }.

On a sharded cluster, DDL (Data Definition Language) operations run with write concern "majority". If you specify a different write concern, the operation overrides the provided write concern with "majority".

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

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:

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.

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 joption 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:

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

w: <number>

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

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

Note

Starting in MongoDB 8.0, { w: "majority" } writes return an acknowledgment after a majority of data-bearing members durably write the oplog entry. The members then asynchronously apply the changes as they read them from their local oplogs. In earlier releases, MongoDB waited until after the members applied the write to return the acknowledgment.

Queries on secondaries immediately after a { w: "majority" } write returns an acknowledgment may read from the collection before the secondary applies changes from the write.

If your application reads from secondaries and requires immediate access to changes made in { w: "majority" } writes, run these operations in a causally consistent session.

To read your own writes on the primary, typically use the"majority" read concern and perform writes with the { w: "majority" } write concern.

If you must use a { w: n } write concern, where n is greater than the calculated majority of the cluster's nodes and the cluster uses the default settings, ensure thewrite concern "j" option is enabled to acknowledge the write to the journal. This is because the "majority" read concern only allows you to read updates that are durable on a majority of nodes in the replica set.

Note

If you perform writes with a { w: n } write concern and n is greater than the calculated majority, but without journaling and with the default cluster settings, you may receive a write acknowledgement before the write is durable on the majority of nodes.

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.

• 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 0members with members[n].votes greater than 0can acknowledge "majority" write operations.
  • Delayed secondaries can return write acknowledgment no earlier than the configured secondaryDelaySecs.
• Starting in MongoDB 5.0, replica set members in theSTARTUP2 state do not participate in write majorities.

The local database does not support write concerns. MongoDB silently ignores any configured write concern for an operation on a collection in the local database.

Tip

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

Warning

To add an arbiter to an existing replica set:

• Typically, if there are two or fewer data-bearing members in the replica set, you might need to first set the cluster wide write concern for the replica set.
• See cluster wide write concern for more information on why you might need to set the cluster wide write concern.

You do not need to change the cluster wide write concern before starting a new replica set with an arbiter.

See also:

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

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

There are important differences between commit quorums and write concerns:

• Index builds use commit quorums.
• Write operations use write concerns.

Each data-bearing node in a cluster is a voting member.

The commit quorum specifies how many data-bearing voting members, or which voting members, including the primary, must be prepared to commit a simultaneous index buildbefore the primary will execute the commit.

The write concern is the level of acknowledgment that the write has propagated to the specified number of instances.

Changed in version 8.0: The commit quorum specifies how many nodes must be ready to finish the index build before the primary commits the index build. In contrast, when the primary has committed the index build, the write concern specifies how many nodes must replicate the index build oplog entry before the command returns success.

In previous releases, when the primary committed the index build, the write concern specified how many nodes must finish the index build before the command returned success.