From f73662efac19f1fb5675c4cfbd0fd81bbea5b206 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 19 Jun 2013 10:44:12 -0400 Subject: [PATCH] DOCS-1492 db.collection.update, sh.addTagRange, sh.waitForDLock --- .../method/db.cloneCollection-param.yaml | 7 +- .../method/db.collection.update-param.yaml | 77 ++++++ .../reference/method/db.collection.update.txt | 259 ++++++++---------- .../method/sh.addTagRange-param.yaml | 53 ++++ source/reference/method/sh.addTagRange.txt | 60 ++-- .../method/sh.waitForDLock-param.yaml | 49 ++++ source/reference/method/sh.waitForDLock.txt | 17 +- 7 files changed, 326 insertions(+), 196 deletions(-) create mode 100644 source/reference/method/db.collection.update-param.yaml create mode 100644 source/reference/method/sh.addTagRange-param.yaml create mode 100644 source/reference/method/sh.waitForDLock-param.yaml diff --git a/source/reference/method/db.cloneCollection-param.yaml b/source/reference/method/db.cloneCollection-param.yaml index 00883e11721..aaa1ddd29ea 100644 --- a/source/reference/method/db.cloneCollection-param.yaml +++ b/source/reference/method/db.cloneCollection-param.yaml @@ -37,7 +37,8 @@ name: query type: document position: 3 description: | - A standard :ref:`MongoDB query document ` to - limit the documents copied as part of the - :method:`db.cloneCollection()` operation. + A standard query document to limit the documents copied as part of the + :method:`db.cloneCollection()` operation. Use the same :ref:`query + selectors ` as used in the :method:`find() + ` method. ... diff --git a/source/reference/method/db.collection.update-param.yaml b/source/reference/method/db.collection.update-param.yaml new file mode 100644 index 00000000000..849bb2c6e57 --- /dev/null +++ b/source/reference/method/db.collection.update-param.yaml @@ -0,0 +1,77 @@ +object: + name: db.collection.update() + type: method +field: + optional: false + type: param +name: query +type: document +position: 1 +description: | + The selection criteria for the update. Use the same :ref:`query + selectors ` as used in the :method:`find() + ` method. +--- +object: + name: db.collection.update() + type: method +field: + optional: false + type: param +name: update +type: document +position: 2 +description: | + The modifications to apply. For details see :ref:`update-parameter` + after this table. +--- +object: + name: db.collection.update() + type: method +field: + optional: true + type: param +name: options +type: document +position: 3 +description: | + New in version 2.2: Specifies whether to perform an :term:`upsert` + and/or a multiple update. Use the ``options`` parameter instead of the + individual ``upsert`` and ``multi`` parameters. +--- +object: + name: db.collection.update() + type: method +field: + optional: true + type: param +name: upsert +type: Boolean +position: 4 +description: | + Specifies whether to create a new document if no document matches the + query criteria. When ``upsert`` is set to ``true``, the + :method:`~db.collection.update()` method either updates an existing + document, or, if no document matches the criteria, inserts a new + document. When ``upsert`` is set to ``false``, + :method:`~db.collection.update()` does not insert a new document if no + match is found. The default value is ``false``. For additional + information, see :ref:`upsert-parameter`. +--- +object: + name: db.collection.update() + type: method +field: + optional: true + type: param +name: multi +type: Boolean +position: 5 +description: | + Specifies whether to update multiple documents that meet the ``query`` + criteria. When ``multi`` is set to ``true``, the + :method:`~db.collection.update()` method updates all documents that + meet the criteria. When ``multi`` is set to ``false``, the method + updates one document. The default value is ``false``. For additional + information, see :ref:`multi-parameter`. +... diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index e9c2402f143..b190764c85d 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -4,12 +4,18 @@ db.collection.update() .. default-domain:: mongodb +Definition +---------- + .. method:: db.collection.update(query, update, [options]) - The :method:`~db.collection.update()` method modifies an - existing document or documents in a collection. By default the - :method:`~db.collection.update()` method updates a single - document. To update all documents in the collection that match the + Modifies an existing document or documents in a collection. + :method:`~db.collection.update()` takes the following parameters: + + .. include:: /reference/method/db.collection.update-param.rst + + :method:`~db.collection.update()` updates a single document by + default. To update all documents in the collection that match the update query criteria, specify the ``multi`` option. To insert a document if no document matches the update query criteria, specify the ``upsert`` option. @@ -26,188 +32,153 @@ db.collection.update() db.collection.update(query, update, , ) - The :method:`~db.collection.update()` method takes the following - parameters: - - :param document query: - - Specifies the selection criteria for the - update. The ``query`` parameter employs the same :ref:`query - selectors ` as used in the - :method:`db.collection.find()` method. - - :param document update: - - Specifies the modifications to apply. - - **If** the ``update`` parameter contains any :ref:`update - operators ` expressions such as the - :operator:`$set` operator expression, then: - - - the ``update`` parameter must contain only ``update - operators`` expressions. - - - the :method:`~db.collection.update()` method updates only - the corresponding fields in the document. - - **If** the ``update`` parameter consists only of ``field: - value`` expressions, then: - - - the :method:`~db.collection.update()` method - *replaces* the document with the ``updates`` document. If - the ``updates`` document is missing the :term:`_id` field, - MongoDB will add the ``_id`` field and assign to it a - unique :term:`objectid` . + Although the update operation may apply mostly to updating the values + of the fields, :method:`update() ` can also + modify the name of the ``field`` in a document using the + :operator:`$rename` operator. - - the :method:`~db.collection.update()` method updates cannot - update multiple documents. +.. _update-parameter: - :param document options: +Update Parameter +~~~~~~~~~~~~~~~~ - .. versionadded:: 2.2 +If the ``update`` parameter contains any :ref:`update operator +` expressions, such as the :operator:`$set` operator +expression, then: - Optional. Specifies whether to perform an :term:`upsert` - and/or a multiple update. Use the ``options`` parameter - instead of the individual ``upsert`` and ``multi`` - parameters. +- the ``update`` parameter must contain only update operator + expressions. - :param boolean upsert: +.. versionadded:: 2.2 - Optional. Specifies an :term:`upsert` operation +- :method:`~db.collection.update()` updates only the corresponding + fields in the document. - The default value is ``false``. When ``true``, the - :method:`~db.collection.update()` method will - update an existing document that matches the ``query`` - selection criteria **or** if no document matches the - criteria, insert a new document with the fields and values of - the ``update`` parameter and if the ``update`` included only - ``update operators``, the ``query`` parameter as well . +If the ``update`` parameter consists only of ``field: value`` +expressions, then: - In version 2.2 of the :program:`mongo` shell, you may also - specify ``upsert`` in the ``options`` parameter. +- :method:`~db.collection.update()` *replaces* the document with the + ``updates`` document. If the ``updates`` document is missing the + :term:`_id` field, MongoDB will add the ``_id`` field and assign to it + a unique :term:`objectid` . - .. note:: +- :method:`~db.collection.update()` updates cannot update multiple + documents. - With ``upsert`` :method:`~db.collection.update()` inserts - a *single* document. +.. _upsert-parameter: - :param boolean multi: +Upsert Parameter +~~~~~~~~~~~~~~~~ - Optional. Specifies whether to update multiple - documents that meet the query criteria. +If ``upsert`` is set to ``true`` and no document matches the criteria, +:method:`~db.collection.update()` inserts a new document with the fields +and values of the ``update`` parameter. If the ``update`` included only +update operators, :method:`~db.collection.update()` inserts the +``query`` parameter as well . - When not specified, the default value is ``false`` and the - :method:`~db.collection.update()` method updates a single - document that meet the ``query`` criteria. +In version 2.2 of the :program:`mongo` shell, you may also specify +``upsert`` in the ``options`` parameter. - When ``true``, the :method:`~db.collection.update()` method - updates all documents that meet the ``query`` criteria. +With ``upsert``, :method:`~db.collection.update()` inserts a *single* +document. - In version 2.2 of the :program:`mongo` shell, you may also - specify ``multi`` in the ``options`` parameter. +.. _multi-parameter: - .. note:: +Multi Parameter +~~~~~~~~~~~~~~~ - The ``multi`` update operation may interleave with other - write operations. For unsharded - collections, you can override this behavior - with the :operator:`$isolated` isolation operator, which - isolates the update operation and blocks - other write operations during the update. See the - :doc:`isolation operator `. +When ``multi`` is set to ``true``, the :method:`~db.collection.update()` +method updates all documents that meet the ``query`` criteria. In +version 2.2 of the :program:`mongo` shell, you may also specify +``multi`` in the ``options`` parameter. - Although the update operation may apply mostly to updating the - values of the fields, the :method:`update() - ` method can also modify the name of the - ``field`` in a document using the :operator:`$rename` operator. +The ``multi`` update operation may interleave with other write +operations. For unsharded collections, you can override this behavior +with the :operator:`$isolated` isolation operator, which isolates the +update operation and blocks other write operations during the update. - .. examples-begin +Examples +-------- - Consider the following examples of the :method:`update() - ` method. These examples all use the 2.2 - interface to specify options in the document form. +The following examples use the 2.2 interface to specify options in the +document form. - - To update specific fields in a document, call the - :method:`~db.collection.update()` method with an - ``update`` parameter using ``field: value`` pairs and expressions - using :ref:`update operators ` as in the - following: +Update Specific Fields in a Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: javascript +Call :method:`~db.collection.update()` with an ``update`` parameter +using ``field: value`` pairs and expressions using :ref:`update +operators ` as in the following: - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) +.. code-block:: javascript - This operation updates a document in the ``products`` - collection that matches the query criteria and sets the value of - the field ``x`` to ``6``, and increment the value of the field - ``y`` by ``5``. All other fields of the document remain the same. + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) - - To replace all the fields in a document with the document as - specified in the ``update`` parameter, call the :method:`update() - ` method with an ``update`` parameter - that consists of *only* ``key: value`` expressions, as in the following: +This operation updates a document in the ``products`` +collection that matches the query criteria and sets the value of +the field ``x`` to ``6``, and increment the value of the field +``y`` by ``5``. All other fields of the document remain the same. - .. code-block:: javascript +Replace All Fields in a Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) +To replace all the fields in a document with the document as +specified in the ``update`` parameter, call the :method:`update() +` method with an ``update`` parameter +that consists of *only* ``key: value`` expressions, as in the following: - This operation selects a document from the ``products`` - collection that matches the query criteria sets the value of the - field ``x`` to ``6`` and the value of the field ``y`` to - ``15``. All other fields of the matched document are *removed*, - except the :term:`_id` field. +.. code-block:: javascript - - To update multiple documents, call the :method:`update() - ` method and specify the ``multi`` option - in the ``options`` argument, as in the following: + db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) - .. code-block:: javascript +This operation selects a document from the ``products`` +collection that matches the query criteria sets the value of the +field ``x`` to ``6`` and the value of the field ``y`` to +``15``. All other fields of the matched document are *removed*, +except the :term:`_id` field. - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } ) +Update Multiple Documents +~~~~~~~~~~~~~~~~~~~~~~~~~ - This operation updates *all* documents in the ``products`` - collection that match the query criteria by setting the value of - the field ``x`` to ``6`` and the value of the field ``y`` to - ``15``. This operation does not affect any other fields in - documents in the ``products`` collection. +Call the :method:`update() ` method and specify +the ``multi`` option, as in the following: - You can perform the same operation by calling the - :method:`~db.collection.update()` method with the ``multi`` - parameter: +.. code-block:: javascript - .. code-block:: javascript + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } ) - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true ) +This operation updates *all* documents in the ``products`` +collection that match the query criteria by setting the value of +the field ``x`` to ``6`` and the value of the field ``y`` to +``15``. This operation does not affect any other fields in +documents in the ``products`` collection. - - To update a document or to insert a new document if no - document matches the query criteria, call the - :method:`~db.collection.update()` and specify the - ``upsert`` option in the ``options`` argument, as in the - following: +You can perform the same operation by calling the +:method:`~db.collection.update()` method with the ``multi`` +parameter: - .. code-block:: javascript +.. code-block:: javascript - db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } ) + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true ) - This operation will: +Upsert +~~~~~~ - - update a single document in the ``products`` collection that - matches the query criteria, setting the value of the field - ``x`` to ``25`` and the value of the field ``y`` to ``50``, *or* +To update a document or to insert a new document if no document matches +the query criteria, call the :method:`~db.collection.update()` and +specify the ``upsert`` option, as in the following: - - if no matching document exists, insert a document in the - ``products`` collection, with the field ``item`` set to - ``magazine``, the field ``x`` set to ``25``, and the field ``y`` - set to ``50``. +.. code-block:: javascript - .. Commented out to encourage people to use the above form. - .. - .. You can also perform the same update by calling the - .. :method:`~db.collection.update()` method with the ``upsert`` - .. parameter: + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } ) - .. .. code-block:: javascript +This operation will: - .. db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true ) +- update a single document in the ``products`` collection that + matches the query criteria, setting the value of the field + ``x`` to ``25`` and the value of the field ``y`` to ``50``, *or* - .. examples-end +- if no matching document exists, insert a document in the + ``products`` collection, with the field ``item`` set to + ``magazine``, the field ``x`` set to ``25``, and the field ``y`` + set to ``50``. diff --git a/source/reference/method/sh.addTagRange-param.yaml b/source/reference/method/sh.addTagRange-param.yaml new file mode 100644 index 00000000000..ac50dc446ae --- /dev/null +++ b/source/reference/method/sh.addTagRange-param.yaml @@ -0,0 +1,53 @@ +object: + name: sh.addTagRange() + type: method +field: + optional: false + type: param +name: namespace +type: string +position: 1 +description: | + The :term:`namespace` of the sharded collection to tag. +--- +object: + name: sh.addTagRange() + type: method +field: + optional: false + type: param +name: minimum +type: document +position: 2 +description: | + The minimum value of the :term:`shard key` range to include in the + tag. Specify the minimum value in the form of ``:``. + This value must be of the same BSON type or types as the shard key. +--- +object: + name: sh.addTagRange() + type: method +field: + optional: false + type: param +name: maximum +type: document +position: 3 +description: | + The maximum value of the shard key range to include in the tag. + Specify the maximum value in the form of ``:``. This + value must be of the same BSON type or types as the shard key. +--- +object: + name: sh.addTagRange() + type: method +field: + optional: false + type: param +name: tag +type: string +position: 4 +description: | + The name of the tag to attach the range specified by the ``minimum`` + and ``maximum`` arguments to. +... diff --git a/source/reference/method/sh.addTagRange.txt b/source/reference/method/sh.addTagRange.txt index 45273c61dae..0ec155e6ab2 100644 --- a/source/reference/method/sh.addTagRange.txt +++ b/source/reference/method/sh.addTagRange.txt @@ -4,36 +4,22 @@ sh.addTagRange() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.addTagRange(namespace, minimum, maximum, tag) .. versionadded:: 2.2 - :param string namespace: Specifies the namespace, in the form of - ``.`` of the sharded - collection that you would like to tag. - - :param document minimum: Specifies the minimum value of the - :term:`shard key` range to include in the tag. - Specify the minimum value in the form of - ``:``. - This value must be of the same BSON type or types - as the shard key. - - :param document maximum: Specifies the maximum value of the shard key range - to include in the tag. Specify the maximum value - in the form of ``:``. - This value must be of the same BSON type or types - as the shard key. + Attaches a range of shard key values to a shard tag created using the + :method:`sh.addShardTag()` method. :method:`sh.addTagRange()` takes + the following arguments: - :param string tag: Specifies the name of the tag to attach the range - specified by the ``minimum`` and ``maximum`` - arguments to. + .. include:: /reference/method/sh.addTagRange-param.rst - :method:`sh.addTagRange()` attaches a range of values of the shard - key to a shard tag created using the :method:`sh.addShardTag()` - method. Use this operation to ensure that the documents that exist - within the specified range exist on shards that have a matching - tag. + You can use this operation to ensure that certain documents, i.e. + those that exist within the specified range, are stored on a specific + shard or set of shards. Always issue :method:`sh.addTagRange()` when connected to a :program:`mongos` instance. @@ -41,25 +27,21 @@ sh.addTagRange() .. note:: If you add a tag range to a collection using - :method:`sh.addTagRange()`, and then later drop the collection - or its database, MongoDB does not remove tag association. If you + :method:`sh.addTagRange()` and then later drop the collection + or its database, MongoDB does not remove the tag association. If you later create a new collection with the same name, the old tag association will apply to the new collection. - .. example:: +Example +------- - Given a shard key of ``{STATE:1,ZIP:1}``, create a tag range covering - ZIP codes in New York State: +Given a shard key of ``{state: 1, zip: 1}``, the following operation +creates a tag range covering zip codes in New York State: - .. code-block:: javascript +.. code-block:: javascript - sh.addTagRange( "exampledb.collection", - { STATE: "NY", ZIP: MinKey }, - { STATE:"NY", ZIP: MaxKey }, - "NY" + sh.addTagRange( "exampledb.collection", + { state: "NY", zip: MinKey }, + { state: "NY", zip: MaxKey }, + "NY" ) - - .. seealso:: - - :method:`sh.addShardTag()`, - :method:`sh.removeShardTag()` diff --git a/source/reference/method/sh.waitForDLock-param.yaml b/source/reference/method/sh.waitForDLock-param.yaml new file mode 100644 index 00000000000..c0b544d4bd8 --- /dev/null +++ b/source/reference/method/sh.waitForDLock-param.yaml @@ -0,0 +1,49 @@ +object: + name: sh.waitForDLock() + type: method +field: + optional: false + type: param +name: lockname +type: string +position: 1 +description: | + The name of the distributed lock. +--- +object: + name: sh.waitForDLock() + type: method +field: + optional: true + type: param +name: wait +type: Boolean +position: 2 +description: | + Set to ``true`` to ensure the balancer is now active. Set to ``false`` + to wait until balancing stops and becomes inactive. +--- +object: + name: sh.waitForDLock() + type: method +field: + optional: false + type: param +name: timeout +type: integer +position: 3 +description: | + Milliseconds to wait. +--- +object: + name: sh.waitForDLock() + type: method +field: + optional: false + type: param +name: interval +type: integer +position: 4 +description: | + Milliseconds to sleep in each waiting cycle. +... diff --git a/source/reference/method/sh.waitForDLock.txt b/source/reference/method/sh.waitForDLock.txt index 32fd6c81444..317c3506e83 100644 --- a/source/reference/method/sh.waitForDLock.txt +++ b/source/reference/method/sh.waitForDLock.txt @@ -4,16 +4,13 @@ sh.waitForDLock() .. default-domain:: mongodb -.. method:: sh.waitForDLock(lockId, onOrNot, timeout, interval) +Definition +---------- - :param string lockId: The name of the distributed lock. +.. method:: sh.waitForDLock(lockname, wait, timeout, interval) - :param Boolean onOrNot: Optional, whether to wait for the lock to be - on (``true``) or off (``false``). + Waits until the specified distributed lock changes state. + :method:`sh.waitForDLock()` is an internal method that takes the + following arguments: - :param integer timeout: Milliseconds to wait. - - :param integer interval: Milliseconds to sleep in each waiting cycle. - - :method:`sh.waitForDLock()` is an internal method that waits until - the specified distributed lock is changes state. + .. include:: /reference/method/sh.waitForDLock-param.rst