diff --git a/source/reference/javascript.txt b/source/reference/javascript.txt index 053f900e201..80e7a9f29d4 100644 --- a/source/reference/javascript.txt +++ b/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`. Otherwise, insert a new + :func:`db.collection.update()` with no :ref:`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,9 +474,9 @@ 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: @@ -484,7 +484,7 @@ Data Aggregation 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 + ``.`` 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 + ``:``. + + :param maximum: Specifies the maximum value of the shard key range + to include in the tag. Specify the minimum value + in the form of ``:``. + + :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 diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 6b73dc290c7..829f4c81bc0 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -151,12 +151,32 @@ reporting for concurrency and use, see the :ref:`locks` and .. TODO add links to current op output documentation when it happens. -Tag Aware Sharding -`````````````````` +Improved Data Center Awareness with Tag Aware Sharding +`````````````````````````````````````````````````````` -:wiki:`Documentation ` -.. TODO see kristina's blog post. +In 2.2, MongoDB adds additional support for geographic distribution or +other custom partitioning in shard clusters. By using this "tag +aware" sharding, you can automatically ensure that data in a +sharded database system is always closest to the application servers +that use that data most frequently. + +Shard tagging controls data location, and is complementary but +separate from replica set tagging which controls data access. For +example, shard tagging can pin all "USA" data to one or more logical +shards, while replica set tagging can control which :program:`mongod` +instances (e.g. "``production``" or "``reporting``") the application +uses to service requests. + +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 +`. Fully Supported Read Preference Semantics `````````````````````````````````````````