edits to write concern tag sets

Author: Sam Kleinman

source/applications/replication.txt

@@ -67,8 +67,8 @@ use the ``wtimeout`` argument. The following example sets the timeout to
 
    db.runCommand( { getlasterror: 1, w: 2, wtimeout:5000 } )
 
-Custom Write Propagation
-~~~~~~~~~~~~~~~~~~~~~~~~
+Modify Default Write Propagation Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can configure your own "default" :dbcommand:`getLastError`
 behavior for a replica set. Use the
@@ -99,6 +99,123 @@ have *no* other arguments.
 .. seealso:: :ref:`write-operations-write-concern` and
    :ref:`connections-write-concern`
 
+Custom Write Propagation Modes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use replica set tags to create custom write concerns using the
+:data:`~local.system.replset.settings.getLastErrorDefaults` and
+:data:`~local.system.replset.settings.getLastErrorModes` replica set
+settings.
+
+.. note::
+
+   Custom write concern modes specify the field name and a number of
+   *distinct* values for that field. By contrast, read preferences use
+   the value of fields in the tag document to direct read operations.
+
+   In some cases, you may be able to use the same tags for read
+   preferences and write concerns; however, you may need to create
+   additional tags for write concerns depending on the requirements of
+   your application.
+
+Single Tag Write Concerns
+`````````````````````````
+
+Consider a five member replica set, where each member has one of the
+following tag sets:
+
+.. code-block:: javascript
+
+   { "use": "reporting" }
+   { "use": "backup" }
+   { "use": "application" }
+   { "use": "application" }
+   { "use": "application" }
+
+You could create a custom write concern mode that will ensure that
+applicable write operations will not return until members with two
+different values of the ``use`` tag have acknowledged the write
+operation. Create the mode with the following sequence of operations
+in the :program:`mongo` shell:
+
+.. code-block:: javascript
+
+   cfg = rs.conf()
+   cfg.settings = { getLastErrorModes: { multiUse: { "use": 2 } } }
+   rs.reconfig(cfg)
+
+.. these examples need to be better so that they avoid overwriting
+   getLastErrorModes upon repetition (i.e. they don't $push documents
+   to getLastErrorModes.)
+
+To use this mode pass the string ``multiUse`` to the ``w`` option of
+:dbcommand:`getLastError` as follows:
+
+.. code-block:: javascript
+
+   db.runCommand( { getlasterror: 1, w: multiUse } )
+
+Specific Custom Write Concerns
+``````````````````````````````
+
+If you have a three member replica with the following tag sets:
+
+.. code-block:: javascript
+
+   { "disk": "ssd" }
+   { "disk": "san" }
+   { "disk": "spinning" }
+
+You cannot specify a custom
+:data:`~local.system.replset.settings.getLastErrorModes` value to
+ensure that the write propagates to the ``san`` before
+returning. However, you may implement this write concern policy by
+creating the following additional tags, so that the set resembles the
+following:
+
+.. code-block:: javascript
+
+   { "disk": "ssd" }
+   { "disk": "san", "disk.san": "san" }
+   { "disk": "spinning" }
+
+Then, create a custom
+:data:`~local.system.replset.settings.getLastErrorModes` value, as
+follows:
+
+.. code-block:: javascript
+
+   cfg = rs.conf()
+   cfg.settings = { getLastErrorModes: { san: { "disk.san": 1 } } }
+   rs.reconfig(cfg)
+
+.. these examples need to be better so that they avoid overwriting
+   getLastErrorModes upon repetition (i.e. they don't $push documents
+   to getLastErrorModes.)
+
+To use this mode pass the string ``san`` to the ``w`` option of
+:dbcommand:`getLastError` as follows:
+
+.. code-block:: javascript
+
+   db.runCommand( { getlasterror: 1, w: san } )
+
+This operation will not return until a replica set member with the tag
+``disk.san`` returns.
+
+You may set a custom write concern mode as the default write concern
+mode using :data:`~local.system.replset.settings.getLastErrorDefaults`
+replica set as in the following setting:
+
+.. code-block:: javascript
+
+   cfg = rs.conf()
+   cfg.settings.getLastErrorDefaults = { ssd:1 }
+   rs.reconfig(cfg)
+
+.. seealso:: :ref:`replica-set-configuration-tag-sets` for further
+   information about replica set reconfiguration and tag sets.
+
 .. index:: read preference
 .. index:: slaveOk
 
@@ -341,26 +458,25 @@ Tag Sets
 ~~~~~~~~
 
 Tag sets allow you to specify custom :ref:`read preferences
-<replica-set-read-preference>` 
+<replica-set-read-preference>`
 and :ref:`write concerns <write-operations-write-concern>`
 so that your application can target
-operations to specific members, based on custom parameters. 
-
-.. important::
-
-   Custom read preferences and write concerns evaluate tags sets in 
-   different ways.
-   
-   Read preferences consider the value of a tag when selecting a member
-   to read from.
-   
-   Write concerns do not utilize the value of a tag to select a
-   member except to consider whether or not the value is unique.
-   
-Custom Read Preferences
-```````````````````````
+operations to specific members, based on custom parameters.
+
+.. note::
+
+   Consider the following properties of read preferences:
 
-A tag set for a read operation may resemble the following:
+   - Custom read preferences and write concerns evaluate tags sets in
+     different ways.
+
+   - Read preferences consider the value of a tag when selecting a
+     member to read from.
+
+   - Write concerns ignore the value of a tag to when selecting a
+     member *except* to consider whether or not the value is unique.
+
+A tag set for a read operation may resemble the following document:
 
 .. code-block:: javascript
 
@@ -419,78 +535,6 @@ For more information on how read preference :ref:`modes
 <replica-set-read-preference-modes>` interact with tag sets, see the
 documentation for each read preference mode.
 
-Custom Write Concerns
-`````````````````````
-
-Replica set tags can be used to create custom write concerns through
-a combination of the tags and the :data:`~local.system.replset.settings.getLastErrorDefaults`
-replica set setting.
-
-You may be able to utilize the same tags you have created for read
-preferences, however you may also need to create additional tags to
-fully utilize custom write concerns.
-
-For example, previously you may have tagged a member with the tags 
-:samp:`disk` and :samp:`use`:
-
-.. code-block:: javascript
-
-   { "disk": "ssd", "use": "reporting" }
-
-In order to direct write operations to the member tagged with :samp:`disk:{ssd}`
-you must add an additional tag:
-
-.. code-block:: javascript
-
-   { "disk.ssd": "ssd"}
-   
-You would then use this tag to create a custom getLastErrorMode:
-
-.. code-block:: javascript
-
-   > var cfg = rs.conf()
-   > cfg.settings = { getLastErrorModes: { ssd: {"disk.ssd":1}} }
-   > rs.reconfig(cfg)
-   
-This creates a custom getLastError mode of :samp:`ssd`, requiring
-at least one member tagged :samp:`ssd` to confirm the write operation.
-
-If, however, you wanted multiple members tagged :samp:`ssd`
-to confirm the write operation, you need to tag each member with
-a different value for the :samp:`disk.ssd` tag.  
-For example:
-
-.. code-block:: javascript
-
-   > cfg.members[2].tags = {"disk.ssd": "APPLE SSD SM512E"}
-   > cfg.members[3].tags = {"disk.ssd": "APPLE SSD SM512E"}
-   > cfg.members[4].tags = {"disk.ssd": "INTEL SSD S3700"}
-   
-And your custom getLastErrorMode would be: 
-
-.. code-block:: javascript
-
-   > cfg.settings = { getLastErrorModes: { ssd: {"disk.ssd":2}} }
-
-This getLastErrorMode directs MongoDB to confirm writes to two replica
-members tagged with unique values for the :samp:`disk.ssd` tag.
-In this example either :samp:`member[{2}]` or :samp:`member[{3}]` would
-satisfy one requirement, and :samp:`member[{4}]` would satisfy
-the requirement for a second member.
-
-The custom write concern can be specified as you would specify a write
-concern or it may be added as a default write concern using the
-the :data:`~local.system.replset.settings.getLastErrorDefaults`
-replica set setting:
-
-.. code-block:: javascript
-
-   > cf.settings.getLastErrorDefaults = {ssd:1}
-
-.. seealso:: :ref:`replica-set-configuration-tag-sets` for further
-   information about replica set reconfiguration and tag sets.
-
-
 .. index:: read preference; behavior
 .. _replica-set-read-preference-behavior: