OPTIONS

Write Concern Reference

Overview

Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concerns determine the level of guarantee. When inserts, updates and deletes have a weak write concern, write operations return quickly. In some failure cases, write operations issued with weak write concerns may not persist. With stronger write concerns, clients wait after sending a write operation for MongoDB to confirm the write operations.

MongoDB provides different levels of write concern to better address the specific needs of applications. Clients may adjust write concern to ensure that the most important operations persist successfully to an entire MongoDB deployment. For other less critical operations, clients can adjust the write concern to ensure faster performance rather than ensure persistence to the entire deployment.

See also

Write Concern for an introduction to write concern in MongoDB.

Available Write Concern

To provide write concern, drivers issue the getLastError command after a write operation and receive a document with information about the last operation. This document’s err field contains either:

  • null, which indicates the write operations have completed successfully, or
  • a description of the last error encountered.

The definition of a “successful write” depends on the arguments specified to getLastError, or in replica sets, the configuration of getLastErrorDefaults. When deciding the level of write concern for your application, see the introduction to Write Concern.

The getLastError command has the following options to configure write concern requirements:

  • j or “journal” option

    This option confirms that the mongod instance has written the data to the on-disk journal and ensures data is not lost if the mongod instance shuts down unexpectedly. Set to true to enable, as shown in the following example:

    db.runCommand( { getLastError: 1, j: "true" } )
    

    If you set journal to true, and the mongod does not have journaling enabled, as with nojournal, then getLastError will provide basic receipt acknowledgment, and will include a jnote field in its return document.

  • w option

    This option provides the ability to disable write concern entirely as well as specifies the write concern operations for replica sets. See Write Concern Considerations for an introduction to the fundamental concepts of write concern. By default, the w option is set to 1, which provides basic receipt acknowledgment on a single mongod instance or on the primary in a replica set.

    The w option takes the following values:

    • 0:

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

      Note

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

    • 1:

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

    • A number greater than 1:

      Guarantees that write operations have propagated successfully to the specified number of replica set members including the primary. 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.

    • A 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.

getLastError also supports a wtimeout setting which allows clients to specify a timeout for the write concern: if you don’t specify wtimeout, or if you give it a value of 0, and the mongod cannot fulfill the write concern the getLastError will block, potentially forever.

For more information on write concern and replica sets, see Write Concern for Replica Sets for more information.

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