DOCS-305 tag aware sharding reference

Author: Sam Kleinman

source/reference/javascript.txt

@@ -118,7 +118,7 @@ Query and Update Methods
 
 .. function:: db.collection.insert(document)
 
-   :param document: Specifies a document to save to the ``collection``.
+   :param document: Specify a document to save to the ``collection``.
 
    :param array documents: Optional alternate. After version 2.2, if
                            you pass an array to :func:`insert()
@@ -132,11 +132,11 @@ Query and Update Methods
 
 .. function:: db.collection.save(document)
 
-   :param document: Specifies a document to save to the ``collection``.
+   :param document: Specify a document to save to the ``collection``.
 
    If :term:`document` has an `_id` field, then perform an
-   :func:`db.collection.update()` with no
-   :ref:`update-operators<update-operators>`.  Otherwise, insert a new
+   :func:`db.collection.update()` with no :ref:`update-operators
+   <update-operators>` as an :term:`upsert`.  Otherwise, insert a new
    document with fields from `document` and a newly generated
    ObjectId() for the ``_id`` field.
 
@@ -474,17 +474,17 @@ Data Aggregation
    The :func:`db.collection.group()` accepts a single :term:`document` that
    contains the following:
 
-   :field key: Specify one or more fields to group by.
+   :field key: Specifies one or more fields to group by.
 
-   :field reduce: Specify a reduce function that operates over all the
+   :field reduce: Specifies a reduce function that operates over all the
                   iterated objects. Typically these aggregator
                   functions perform some sort of summing or
                   counting. The reduce function takes two arguments:
                   the current document and an aggregation counter
                   object.
 
    :field initial: The starting value of the aggregation counter
-                  object.
+                   object.
 
    :field keyf: Optional. An optional function that returns a "key
                 object" for use as the grouping key. Use
@@ -728,8 +728,8 @@ Database
 
    :param string password: Specifies the corresponding password.
 
-   :param boolean readOnly: Optionally restricts a user to read-privileges
-                            only. Defaults to false.
+   :param boolean readOnly: Optional. Restrict a user to
+                            read-privileges only. Defaults to false.
 
    Use this function to create new database users, by specifying a
    username and password as arguments to the command. If you want to
@@ -1110,7 +1110,7 @@ Database
 
 .. function:: db.setProfilingLevel(level, [slowms])
 
-   :param level: Specify a profiling level, see list of possible
+   :param level: Specifies a profiling level, see list of possible
                  values below.
 
    :param slowms: Optionally modify the threshold for the profile to
@@ -1730,6 +1730,75 @@ Sharding
              cluster`, including data regarding the distribution of
              chunks.
 
+.. function:: sh.addShardTag(shard, tag)
+
+   .. versionadded:: 2.2
+
+   :param shard: Specifies the name of the shard that you want to give
+                 a specific tag.
+
+   :param tag: Specifies the name of the tag that you want to add to
+               the shard.
+
+   :func:`sh.addShardTag()` associates a shard with a tag or
+   identifier. MongoDB can use these identifiers, to "home" or attach
+   (i.e. with :func:`sh.addTagRange()`) specific data to a specific
+   shard.
+
+   Always issue :func:`sh.addShardTag()` when connected to a
+   :program:`mongos` instance. The following example adds three tags,
+   ``LGA``, ``EWR``, and ``JFK``, to three shards:
+
+   .. code-block:: javascript
+
+      sh.addShardTag("shard0000", "LGA")
+      sh.addShardTag("shard0001", "EWR")
+      sh.addShardTag("shard0002", "JFK")
+
+.. function:: sh.addTagRange(namespace, minimum, maximum, tag)
+
+   .. versionadded:: 2.2
+
+   :param namespace: Specifies the namespace, in the form of
+                     ``<database>.<collection>`` of the sharded
+                     collection that you would like to tag.
+
+   :param minimum: Specifies the minimum value of the :term:`shard
+                   key` range to include in the tag. Specify the
+                   minimum value in the form of
+                   ``<fieldname>:<value>``.
+
+   :param maximum: Specifies the maximum value of the shard key range
+                   to include in the tag.  Specify the minimum value
+                   in the form of ``<fieldname>:<value>``.
+
+   :param tag: Specifies the name of the tag to attach the range
+               specified by the ``minimum`` and ``maximum`` arguments
+               to.
+
+   :func:`sh.addTagRange()` attaches a range of values of the shard
+   key to a shard tag created using the :func:`sh.addShardTag()`
+   helper. Use this operation to ensure that the documents that exist
+   within the specified range exist on shards that have a matching
+   tag.
+
+   Always issue :func:`sh.addTagRange()` when connected to a
+   :program:`mongos` instance.
+
+.. function:: sh.removeShardTag(shard, tag)
+
+   .. versionadded:: 2.2
+
+   :param shard: Specifies the name of the shard that you want
+                 to remove a tag from.
+
+   :param tag: Specifies the name of the tag that you want to remove
+               from the shard.
+
+   Removes the association between a tag and a shard. Always issue
+   :func:`sh.removeShardTag()` when connected to a :program:`mongos`
+   instance.
+
 .. function:: sh.help()
 
    :returns: a basic help text for all sharding related shell

source/release-notes/2.2.txt

@@ -151,12 +151,26 @@ reporting for concurrency and use, see the :ref:`locks` and
 
 .. TODO add links to current op output documentation when it happens.
 
-Tag Aware Sharding
-``````````````````
-
-:wiki:`Documentation <Tag+Aware+Sharding>`
-
-.. TODO see kristina's blog post.
+Improved Data Center Awareness with Tag Aware Sharding
+``````````````````````````````````````````````````````
+
+In 2.2, MongoDB adds additional support for geographically distributed
+database systems. This "tag aware" sharding combines with work done
+with :ref:`read preferences <replica-set-read-preference>` and
+:ref:`tag sets <replica-set-configuration-tag-sets>` to make it
+possible to ensure that data in a geographically distributed sharded
+cluster is always closest to the application servers that will use
+that data the most.
+
+See the documentation of the following helpers in the :program:`mongo`
+shell that support tagged sharding configuration:
+
+- :func:`sh.addShardTag()`
+- :func:`sh.addTagRange()`
+- :func:`sh.removeShardTag()`
+
+Also, see the :wiki:`wiki page for tag aware sharding
+<Tag+Aware+Sharding>`.
 
 Fully Supported Read Preference Semantics
 `````````````````````````````````````````