updates to tag aware sharding documents

Author: Sam Kleinman

source/administration/tag-aware-sharding.txt

@@ -24,7 +24,7 @@ sharding in MongoDB deployments.
 
 .. note::
 
-   Shard key tags are entirely distinct from :ref:`replica set member
+   Shard key rage tags are entirely distinct from :ref:`replica set member
    tags <replica-set-read-preference-tag-sets>`.
 
 Behavior and Operations
@@ -33,20 +33,19 @@ Behavior and Operations
 Tags in a sharded cluster are pieces of metadata that dictate the
 policy and behavior of the cluster balancer :term:`balancer`. Using
 tags, you may associate individual shards in a cluster with one or
-more strings, or tags. Then, you can assign this tag string to a range
+more tags. Then, you can assign this tag string to a range
 of :term:`shard key` values for a sharded collection. When migrating a
 chunk, the balancer will select a destination shard based on the
 configured tag ranges.
 
-To migrate chunks in a tagged environment, the balancer selects a
-target shard with a tag range that has an *upper* bound that *greater
-than* the migrating chunk's *lower* bound. If a shard with a matching
-tagged range exists, the balancer will migrate the chunk to that
-shard.
+The balancer migrates chunks in tagged ranges to shards with those
+tags, if tagged shards are not balanced. [#specific-tagged-migrations]_
 
-.. note:: The balancer may migrate chunks to tagged shards that
-   contain values that exceed the upper bound of the selected tag
-   range.
+.. note::
+
+   Because a single chunk may span different tagged shard key ranges,
+   the balancer may migrate chunks to tagged shards that contain
+   values that exceed the upper bound of the selected tag range.
 
 .. example::
 
@@ -63,11 +62,20 @@ shard.
    values ranging between ``150`` and ``220`` to a shard tagged
    ``NYC``, since ``150`` is closer to ``200`` than ``300``.
 
-After configuring shard tags, the cluster may take some time to
-reach the proper distribution of data, depending on the division of
-chunks (i.e. splits) and the current distribution of data in the
-cluster. Once configured, the balancer will respect tag ranges during
-future :ref:`balancing rounds <sharding-internals-balancing>`.
+After configuring tags on shards and ranges of the shard key, the
+cluster may take some time to reach the proper distribution of data,
+depending on the division of chunks (i.e. splits) and the current
+distribution of data in the cluster. Once configured, the balancer
+will respect tag ranges during future :ref:`balancing rounds
+<sharding-internals-balancing>`.
+
+.. [#specific-tagged-migrations] To migrate chunks in a tagged
+   environment, the balancer selects a target shard with a tag range
+   that has an *upper* bound that is *greater than* the migrating
+   chunk's *lower* bound. If a shard with a matching tagged range
+   exists, the balancer will migrate the chunk to that shard.
+
+
 
 Administer Shard Tags
 ---------------------
@@ -101,11 +109,11 @@ the ``NRT`` tag from a shard:
 Tag a Shard Key Range
 ~~~~~~~~~~~~~~~~~~~~~
 
-To assign a range of shard key values to a tag, use the
+To assign a tag to a range of shard keys use the
 :method:`sh.addTagRange()` method when connected to a
 :program:`mongos` instance. Any given shard key range may only have
-*one* assigned tag. However, you may assign the same tag to multiple
-shard key rage.
+*one* assigned tag. You cannot overlap defined ranges, or tag the same
+range more than once.
 
 .. example::
 
@@ -122,6 +130,11 @@ shard key rage.
       sh.addTagRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC")
       sh.addTagRange("records.users", { zipcode: "94102" }, { zipcode: "94135" }, "SFO")
 
+.. note::
+
+   Shard rages are always inclusive of the lower value and exclusive
+   of the upper boundary.
+
 Remove a Tag From a Shard Key Range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/applications/replication.txt

@@ -29,8 +29,8 @@ After the :doc:`driver write concern change
 </release-notes/drivers-write-concern>` all officially supported
 MongoDB drivers enable write concern by default.
 
-Write Propagation
-~~~~~~~~~~~~~~~~~
+Verify Write Operations
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The default write concern confirms write operations only on the
 primary.  You can configure write concern to confirm write operations
@@ -67,8 +67,8 @@ use the ``wtimeout`` argument. The following example sets the timeout to
 
    db.runCommand( { getLastError: 1, w: 2, wtimeout:5000 } )
 
-Modify Default Write Propagation Operation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Modify Default Write Concern
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can configure your own "default" :dbcommand:`getLastError`
 behavior for a replica set. Use the
@@ -99,8 +99,8 @@ have *no* other arguments.
 .. seealso:: :ref:`write-operations-write-concern` and
    :ref:`connections-write-concern`
 
-Custom Write Propagation Modes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Custom Write Concerns
+~~~~~~~~~~~~~~~~~~~~~
 
 You can use replica set tags to create custom write concerns using the
 :data:`~local.system.replset.settings.getLastErrorDefaults` and
@@ -141,7 +141,7 @@ in the :program:`mongo` shell:
 .. code-block:: javascript
 
    cfg = rs.conf()
-   cfg.settings = { getLastErrorModes: { multiUse: { "use": 2 } } }
+   cfg.settings = { getLastErrorModes: { use2: { "use": 2 } } }
    rs.reconfig(cfg)
 
 .. these examples need to be better so that they avoid overwriting
@@ -153,7 +153,7 @@ To use this mode pass the string ``multiUse`` to the ``w`` option of
 
 .. code-block:: javascript
 
-   db.runCommand( { getLastError: 1, w: multiUse } )
+   db.runCommand( { getLastError: 1, w: use2 } )
 
 Specific Custom Write Concerns
 ``````````````````````````````

source/data-center-awareness.txt

@@ -1,28 +1,28 @@
 :orphan:
-   
+
 =====================
 Data Center Awareness
 =====================
 
 .. default-domain:: mongodb
 
-MongoDB provides a number of features that allow application developers
-and database administrators to customize the behavior of a
+MongoDB provides a number of features that allow application
+developers and database administrators to customize the behavior of a
 :term:`sharded cluster` or :term:`replica set` deployment so that
-MongoDB may be "data center aware," or allow operational separation and
-segregation based on location. 
+MongoDB may be *more* "data center aware," or allow operational
+separation and segregation based on location.
 
 MongoDB also supports segregation based
 on functional parameters, to ensure that certain :program:`mongod`
 instances are only used for reporting workloads or that certain
 high-frequency portions of a sharded collection only exist on specific
-shards. 
+shards.
 
-Consider the following documents: 
+Consider the following documents:
 
-.. toctree:: 
+.. toctree::
    :maxdepth: 1
-              
+
    /administration/operational-segregation
    /administration/tag-aware-sharding
    /tutorial/deploy-geographically-distributed-replica-set