Permalink
Fetching contributors…
Cannot retrieve contributors at this time
282 lines (198 sloc) 8.03 KB
.. _write-operations-write-concern:
.. _write-concern-operation:
.. _write-concern-internals:
.. _write-concern:
=============
Write Concern
=============
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Write concern describes the level of acknowledgement requested from
MongoDB for write operations to a standalone :program:`mongod` or to
:doc:`replica sets </replication>` or to
:doc:`sharded clusters </sharding>`. In
sharded clusters, :program:`mongos` instances will pass the write
concern on to the shards.
.. versionchanged:: 2.6
A new protocol for :ref:`write operations
<rel-notes-write-operations>` integrates write concerns with the
write operations and eliminates the need to call the
:dbcommand:`getLastError` command. Previous versions required a
:dbcommand:`getLastError` command immediately after a write
operation to specify the write concern.
Write Concern Specification
---------------------------
Write concern can include the following fields:
.. code-block:: javascript
{ w: <value>, j: <boolean>, wtimeout: <number> }
- the :ref:`w <wc-w>` option to request acknowledgement that the write
operation has propagated to a specified number of :program:`mongod`
instances or to :program:`mongod` instances with specified tags.
- the :ref:`j <wc-j>` option to request acknowledgement that the write
operation has been written to the journal, and
- the :ref:`wtimeout <wc-wtimeout>` option to specify a time limit to
prevent write operations from blocking indefinitely.
.. _wc-w:
``w`` Option
~~~~~~~~~~~~
The ``w`` option requests acknowledgement that the write operation has
propagated to a specified number of :program:`mongod` instances or to
:program:`mongod` instances with specified tags.
Using the ``w`` option, the following ``w: <value>`` write concerns are
available:
.. list-table::
:header-rows: 1
:widths: 20 80
* - Value
- Description
* - .. writeconcern:: <number>
- Requests acknowledgement that the write operation has propagated
to the specified number of :program:`mongod` instances. For
example:
``w: 1``
Requests acknowledgement that the write operation has
propagated to the standalone :program:`mongod` or the primary
in a replica set. ``w: 1`` is the default write concern for
MongoDB.
``w: 0``
Requests no acknowledgement of the write operation. However, ``w:
0`` may return information about socket exceptions and
networking errors to the application.
If you specify ``w: 0`` but include :ref:`j: true <wc-j>`, the
:ref:`j: true <wc-j>` prevails to request acknowledgement from
the standalone :program:`mongod` or the primary of a replica
set.
Numbers greater than 1 are valid only for replica sets to
request acknowledgement from specified number of members,
including the primary.
See :ref:`wc-ack-behavior` for when :program:`mongod` instances
acknowledge the write.
* - .. writeconcern:: "majority"
- Requests acknowledgement that write operations have propagated to
the majority of voting nodes [#majority-definition]_, including
the primary.
After the write operation returns with a :writeconcern:`w:
"majority" <"majority">` acknowledgement to the client, the
client can read the result of that write with a
:readconcern:`"majority"` readConcern.
See :ref:`wc-ack-behavior` for when :program:`mongod` instances
acknowledge the write.
* - .. writeconcern:: <tag set>
- Requests acknowledgement that the write operations have
propagated to a replica set member with the specified :ref:`tag
<replica-set-configuration-tag-sets>`. See
:ref:`wc-ack-behavior` for when :program:`mongod` instances
acknowledge the write.
.. seealso:: :doc:`/reference/replica-set-protocol-versions`
.. _wc-j:
``j`` Option
~~~~~~~~~~~~
The ``j`` option requests acknowledgement from MongoDB that
the write operation has been written to the :doc:`journal
</core/journaling>`.
.. list-table::
:widths: 20 80
* - .. writeconcern:: j
- If ``j: true``, requests acknowledgement that the
:program:`mongod` instances, as specified in the :ref:`w:
\<value\> <wc-w>`, 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.
.. versionchanged:: 3.2
.. include:: /includes/note-write-concern-journaled-replication.rst
.. note::
- Specifying a write concern that includes ``j: true`` to a
:program:`mongod` instance that is running without journaling
produces an error.
- For replica sets using :rsconf:`protocolVersion: 1
<protocolVersion>`, if journaling is enabled, :writeconcern:`w:
"majority" <"majority">` may imply ``j: true``. The
:rsconf:`writeConcernMajorityJournalDefault` replica set
configuration setting determines the behavior. See
:ref:`wc-ack-behavior` for details.
.. _wc-wtimeout:
``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.
.. _wc-ack-behavior:
Acknowledgement Behavior
------------------------
The :ref:`w <wc-w>` option and the :ref:`j <wc-j>` option determine
when :program:`mongod` instances acknowledge write operations.
Standalone
~~~~~~~~~~
A standalone :program:`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 acknowledgement behavior for a
standalone and the relevant write concerns:
.. list-table::
:header-rows: 1
:widths: 35 40 25 20
* -
- ``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::
.. include:: /includes/extracts/no-journaling-rollback.rst
Replica Sets
~~~~~~~~~~~~
.. versionchanged:: 3.4
A replica set acknowledges a write operation either after the specified
number of members apply the write in memory or after they write to the
on-disk journal. The number of members is specified by the :ref:`w:
\<value\> <wc-w>` setting. The following table lists the
acknowledgement behavior for these members and the relevant write
concerns [#3.2-behavior]_:
.. list-table::
:header-rows: 1
:widths: 22 50 22 20
* -
- ``j`` is unspecified
- ``j:true``
- ``j:false``
* - ``w: "majority"``
- Depends on the value of
:rsconf:`writeConcernMajorityJournalDefault`.
- If true, On-disk journal.
- If false, In memory.
.. versionchanged:: 3.4
- On-disk journal
- In memory
* - ``w: <number>``
- In memory
- On-disk journal
- In memory
.. note::
.. include:: /includes/extracts/no-journaling-rollback.rst
.. [#3.2-behavior]
For the behavior in version 3.2, refer to the :v3.2:`3.2 manual
</reference/write-concern>`.
.. [#majority-definition]
.. versionchanged:: 3.0
Prior to MongoDB 3.0, ``w: "majority"`` refers to the majority of
the replica set's members instead of the majority of the replica
set's voting members.
.. include:: /includes/fact-master-slave-majority.rst