OPTIONS

Write Concern Reference

Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation.

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.

Read Isolation Behavior

MongoDB allows clients to read documents inserted or modified before it commits these modifications to disk, regardless of write concern level or journaling configuration. As a result, applications may observe two classes of behaviors:

  • For systems with multiple concurrent readers and writers, MongoDB will allow clients to read the results of a write operation before the write operation returns.
  • If the mongod terminates before the journal commits, even if a write returns successfully, queries may have read data that will not exist after the mongod restarts.

Other database systems refer to these isolation semantics as read uncommitted. For all inserts and updates, MongoDB modifies each document in isolation: clients never see documents in intermediate states. For multi-document operations, MongoDB does not provide any multi-document transactions or isolation.

When mongod returns a successful journaled write concern, the data is fully committed to disk and will be available after mongod restarts.

For replica sets, write operations are durable only after a write replicates and commits to the journal of a majority of the voting members of the set. [1] MongoDB regularly commits data to the journal regardless of journaled write concern: use the commitIntervalMs to control how often a mongod commits the journal.

[1]For the purposes of write concern, w:majority refers to a majority of all the members in the set. As a result, arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

Available Write Concern

Write concern can include the w option to specify the required number of acknowledgments before returning, the j option to require writes to the journal before returning, and wtimeout option to specify a time limit to prevent write operations from blocking indefinitely.

In sharded clusters, mongos instances will pass the write concern on to the shard.

w Option

The w option provides the ability to disable write concern entirely as well as specify the write concern for replica sets.

MongoDB uses w: 1 as the default write concern. w: 1 provides basic receipt acknowledgment.

The w option accepts the following values:

Value Description
1

Provides acknowledgment of write operations on a standalone mongod or the primary in a replica set.

This is the default write concern for MongoDB.

0

Disables basic acknowledgment of write operations, but returns information about socket exceptions and networking errors to the application.

If you disable basic write operation acknowledgment but require journal commit acknowledgment, the journal commit prevails, and the server will require that mongod acknowledge the write operation.

<Number greater than 1>

Guarantees that write operations have propagated successfully to the specified number of replica set members including the primary.

For example, w: 2 indicates acknowledgements from the primary and at least one secondary.

If you set w to a number that is greater than the number of set members that hold data, MongoDB waits for the non-existent members to become available, which means MongoDB blocks indefinitely.

"majority"

Confirms that write operations have propagated to the majority of configured replica set: a majority of the set’s configured members must acknowledge the write operation before it succeeds. This allows you to avoid hard coding assumptions about the size of your replica set into your application.

Changed in version 2.6: In Master/Slave deployments, MongoDB treats w: "majority" as equivalent to w: 1. In earlier versions of MongoDB, w: "majority" produces an error in master/slave deployments.

<tag set> By specifying a tag set, you can have fine-grained control over which replica set members must acknowledge a write operation to satisfy the required level of write concern.

j Option

The j option confirms that the mongod instance has written the data to the on-disk journal. This ensures that data is not lost if the mongod instance shuts down unexpectedly. Set to true to enable.

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

Note

Requiring journaled write concern in a replica set only requires a journal commit of the write operation to the primary of the set regardless of the level of replica acknowledged write concern.

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.