From cf5094bfd5cb9eb2c290443fbc03aa3de78399f5 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 13:26:38 -0400 Subject: [PATCH 1/3] DOCS-505 v2.2 has new update() API --- .../reference/method/db.collection.update.txt | 236 ++++++++++++++---- 1 file changed, 193 insertions(+), 43 deletions(-) diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index d339df31a55..6a250d03e55 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -4,46 +4,196 @@ db.collection.update() .. default-domain:: mongodb -.. method:: db.collection.update(query, update, [upsert,] [multi]) - - The :method:`db.collection.update()` takes the following four arguments. - - :param query: A query object that selects one or more records to - update. Use the :ref:`query selectors - ` as you would in a :method:`db.collection.find()` - operation. - - :param update: A :term:`document`. If the update document's fields - include any :ref:`update operators `, - then all the fields must be update operators, and - applies those operators to values in the matching - document. If none of the update document's the - fields are update operators, then :method:`update() - ` replaces all of the - matching document's fields except the :term:`_id` - with the fields in the update document. - - :param boolean upsert: Optional. Defaults to ``false``. When - ``true``, this operation will update a - document if one matches the query portion - and insert a new document if *no* documents - match the query portion. The new document - will consist of the union of fields and - values from the query document and update - document. - - :param boolean multi: Optional. Defaults to ``false``. When - ``true``, all the operation updates all - documents that match the query. When - ``false``, update only the first document - that matches the query. - - Provides the ability to update an existing document in the current - database and collection. The second argument to :method:`db.collection.update()` - takes the form of a :term:`document`. See ":ref:`update-operators`" - for a reference of all operators that affect updates. - - .. note:: - - An upsert operation only affects *one* document, and cannot - update multiple documents. +.. method:: db.collection.update(query, update, [options]) + + .. versionchanged:: 2.2 + + The :method:`db.collection.update()` method provides the ability to + modify a document in a collection. + + The default behavior of the :method:`db.collection.update()` method + is to update a single document. You can specify the ``multi`` option to + update multiple documents that meet the ``query`` criteria. + Additionally, you can specify the ``upsert`` option to have the + :method:`db.collection.update()` method insert a document into the + collection if no document meets the ``query`` criteria. + + Starting in version 2.2, the :method:`db.collection.update()` method + can take an ``options`` :term:`document` as a parameter to specify + the ``multi`` and the ``upsert`` options. However, the + :method:`db.collection.update()` still supports the ``upsert`` and + ``multi`` parameters to specify the ``multi`` and the ``upsert`` + options: + + .. code-block:: javascript + + db.collection.update(query, update, [upsert,] [multi]) + + The :method:`db.collection.update()` method takes the following + parameters: + + :param document query: + + A :term:`document` that 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. + + Consider the following example: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, ... } + + This query excerpt will update the document(s) in the + ``products`` collection with the ``item`` field value equal + to ``book`` and the ``qty`` field value greater than ``5``. + + :param document update: + + A :term:`document` that 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 :ref:`update + operators ` expressions. + + - the :method:`db.collection.update()` method updates only + the corresponding fields in the document. + + Consider the following example: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) + + This query will update in the ``products`` collection a + single document that matches the ``query`` criteria and set + the value of the field ``x`` to ``6`` and increment the + value of the field ``y`` by ``5``. All other fields of the + modified document will remain the same. + + - If the ``update`` parameter consists only of ``field: + value`` expressions, + + - the :method:`db.collection.update()` method updates the + document to contain only the :term:`_id` field and the + fields in the ``updates`` parameter. + + - the :method:`db.collection.update()` method updates + cannot update multiple documents. + + Consider the following example: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) + + This query will update in the ``products`` collection a + single document that matches the ``query`` criteria and set + the value of the field ``x`` to ``6`` and set the value of + the field ``y`` to ``15``. *All other fields* of the + modified document will be removed other than the + :term:`_id` field. + + :param document options: + + Optional. A :term:`document` that specifies whether to + perform an :term:`upsert` and/or a multiple update. You can + use the ``options`` parameter instead of the individual + ``upsert`` and ``multi`` parameters. + + Consider the following example which specifies the ``multi`` option: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } ) + + This query will update **all** documents in the ``products`` + collection that matches the ``query`` criteria, setting the + value of the field ``x`` to ``6`` and the value of the field + ``y`` to ``15``. All other fields in the updated documents + remain unchanged. + + Consider the following example which specifies the ``upsert`` option: + + .. code-block:: javascript + + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { upsert: true } ) + + This query will either: + + - update a single document in the ``products`` collection + that matches the ``query`` criteria, setting the value of + the field ``x`` to ``6`` and the value of the field ``y`` + to ``15``, *or* + + - if no matching document exists, insert a document in the + ``products`` collection, with the field ``item`` set to + ``book``, the field ``x`` set to ``25``, and the field + ``y`` set to ``50``. + + :param boolean upsert: + + Optional. A boolean that specifies whether to perform + an :term:`upsert`. + + When not specified, 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 ``query`` and ``update``. + + Consider the following example: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, true ) + + This query will either: + + - update an existing document that matches the ``query`` + criteria, setting the field ``x`` to ``25`` and the field + ``y`` to ``50``, *or* + + - if no matching document exists, insert into the + ``products`` collection a new document with the field + ``item`` set to ``book``, the field ``x`` set to ``25``, + and the field ``y`` set to ``50``. + + Starting in version 2.2, you can use the ``options`` + parameter instead of the ``upsert`` parameter. + + .. note:: + + An upsert operation affects only *one* document, and + cannot update multiple documents. + + :param boolean multi: + + Optional. A boolean that specifies whether to update multiple + documents that meet the ``query`` criteria. + + When not specified, the default value is ``false`` and the + :method:`db.collection.update()` method updates a single + document that meet the ``query`` criteria. + + When ``true``, the :method:`db.collection.update()` method + updates all documents that meet the ``query`` criteria. + + Consider the following example: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, false, true ) + + This query will update **all** documents 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``. + + Starting in version 2.2, you can use the ``options`` + parameter instead of the ``multi`` parameter. From 931e4b9ef6fc132f89debdc0e06f5bb4dc5672f4 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 14:26:31 -0400 Subject: [PATCH 2/3] DOCS-505 update() method has new api --- .../reference/method/db.collection.update.txt | 205 +++++++++--------- 1 file changed, 97 insertions(+), 108 deletions(-) diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index 6a250d03e55..bb721c8bf98 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -6,7 +6,9 @@ db.collection.update() .. method:: db.collection.update(query, update, [options]) - .. versionchanged:: 2.2 + .. versionchanged:: 2.2 + Added new interface to take an ``options`` :term:`document` as a + parameter to specify the ``multi`` and the ``upsert`` options. The :method:`db.collection.update()` method provides the ability to modify a document in a collection. @@ -33,70 +35,35 @@ db.collection.update() parameters: :param document query: - + A :term:`document` that 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. - Consider the following example: - - .. code-block:: javascript - - db.products.update( { item: "book", qty: { $gt: 5 } }, ... } - - This query excerpt will update the document(s) in the - ``products`` collection with the ``item`` field value equal - to ``book`` and the ``qty`` field value greater than ``5``. - :param document update: - - A :term:`document` that 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 :ref:`update - operators ` expressions. - - - the :method:`db.collection.update()` method updates only - the corresponding fields in the document. - - Consider the following example: - - .. code-block:: javascript - - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) - - This query will update in the ``products`` collection a - single document that matches the ``query`` criteria and set - the value of the field ``x`` to ``6`` and increment the - value of the field ``y`` by ``5``. All other fields of the - modified document will remain the same. - - If the ``update`` parameter consists only of ``field: - value`` expressions, + A :term:`document` that specifies the modifications to apply. - - the :method:`db.collection.update()` method updates the - document to contain only the :term:`_id` field and the - fields in the ``updates`` parameter. + **If** the ``update`` parameter contains any :ref:`update + operators ` expressions such as the + :operator:`$set` operator expression, then: - - the :method:`db.collection.update()` method updates - cannot update multiple documents. + - the ``update`` parameter must contain only :ref:`update + operators ` expressions. - Consider the following example: + - the :method:`db.collection.update()` method updates only + the corresponding fields in the document. - .. code-block:: javascript + **If** the ``update`` parameter consists only of ``field: + value`` expressions, then: - db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) + - the :method:`db.collection.update()` method updates the + document to contain only the :term:`_id` field and the + fields in the ``updates`` parameter. - This query will update in the ``products`` collection a - single document that matches the ``query`` criteria and set - the value of the field ``x`` to ``6`` and set the value of - the field ``y`` to ``15``. *All other fields* of the - modified document will be removed other than the - :term:`_id` field. + - the :method:`db.collection.update()` method updates cannot + update multiple documents. :param document options: @@ -105,36 +72,6 @@ db.collection.update() use the ``options`` parameter instead of the individual ``upsert`` and ``multi`` parameters. - Consider the following example which specifies the ``multi`` option: - - .. code-block:: javascript - - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } ) - - This query will update **all** documents in the ``products`` - collection that matches the ``query`` criteria, setting the - value of the field ``x`` to ``6`` and the value of the field - ``y`` to ``15``. All other fields in the updated documents - remain unchanged. - - Consider the following example which specifies the ``upsert`` option: - - .. code-block:: javascript - - db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { upsert: true } ) - - This query will either: - - - update a single document in the ``products`` collection - that matches the ``query`` criteria, setting the value of - the field ``x`` to ``6`` and the value of the field ``y`` - to ``15``, *or* - - - if no matching document exists, insert a document in the - ``products`` collection, with the field ``item`` set to - ``book``, the field ``x`` set to ``25``, and the field - ``y`` set to ``50``. - :param boolean upsert: Optional. A boolean that specifies whether to perform @@ -147,23 +84,6 @@ db.collection.update() criteria, insert a new document with the fields and values of the ``query`` and ``update``. - Consider the following example: - - .. code-block:: javascript - - db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, true ) - - This query will either: - - - update an existing document that matches the ``query`` - criteria, setting the field ``x`` to ``25`` and the field - ``y`` to ``50``, *or* - - - if no matching document exists, insert into the - ``products`` collection a new document with the field - ``item`` set to ``book``, the field ``x`` set to ``25``, - and the field ``y`` set to ``50``. - Starting in version 2.2, you can use the ``options`` parameter instead of the ``upsert`` parameter. @@ -184,16 +104,85 @@ db.collection.update() When ``true``, the :method:`db.collection.update()` method updates all documents that meet the ``query`` criteria. - Consider the following example: + Starting in version 2.2, you can use the ``options`` + parameter instead of the ``multi`` parameter. - .. code-block:: javascript +Examples +~~~~~~~~ - db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, false, true ) +- To update specific fields in a single document, you can call the + :method:`db.collection.update()` method with the ``update`` parameter + consisting of :ref:`update operators ` expressions, + as in the following: - This query will update **all** documents 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``. + .. code-block:: javascript - Starting in version 2.2, you can use the ``options`` - parameter instead of the ``multi`` parameter. + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) + + This query will update in the ``products`` collection a single + document that matches the ``query`` criteria and set the value of the + field ``x`` to ``6`` and increment the value of the field ``y`` by + ``5``. All other fields of the modified document will remain the same. + +- To replace completely all the fields in a single document with those + in the ``update`` parameter, you can call the + :method:`db.collection.update()` method with the ``update`` parameter + consisting of ``key:value`` expressions, as in the following: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) + + This query will update in the ``products`` collection a single + document that matches the ``query`` criteria and set the value of the + field ``x`` to ``6`` and set the value of the field ``y`` to ``15``. + All other fields of the modified document will be **removed** other + than the :term:`_id` field. + +- To update multiple documents, you can call the + :method:`db.collection.update()` method with the ``options`` + parameter specifying the ``multi`` option, as in the following: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } ) + + This query will update **all** documents in the ``products`` + collection that matches the ``query`` criteria, setting the value of + the field ``x`` to ``6`` and the value of the field ``y`` to ``15``. + All other fields in the updated documents remain unchanged. + + You can also perform the same update by calling the + :method:`db.collection.update()` method with the ``multi`` parameter: + + .. code-block:: javascript + + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true ) + +- To update a single document or to insert a new document if no + document matches the ``query`` criteria, you can call the + :method:`db.collection.update()` method with the ``options`` + parameter specifying the ``upsert`` option, as in the following: + + .. code-block:: javascript + + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } ) + + This query will either: + + - 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* + + - 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``. + + You can also perform the same update by calling the + :method:`db.collection.update()` method with the ``upsert`` parameter: + + .. code-block:: javascript + + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true ) + + \ No newline at end of file From 885d51a085b34e99959a26be401b29082c513f62 Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 18 Sep 2012 15:05:43 -0400 Subject: [PATCH 3/3] DOCS-505 v2.2 has improved update() api --- .../reference/method/db.collection.update.txt | 134 +++++++++--------- 1 file changed, 69 insertions(+), 65 deletions(-) diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index bb721c8bf98..f52220a7759 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -14,13 +14,14 @@ db.collection.update() modify a document in a collection. The default behavior of the :method:`db.collection.update()` method - is to update a single document. You can specify the ``multi`` option to - update multiple documents that meet the ``query`` criteria. - Additionally, you can specify the ``upsert`` option to have the - :method:`db.collection.update()` method insert a document into the - collection if no document meets the ``query`` criteria. - - Starting in version 2.2, the :method:`db.collection.update()` method + is to update a single document. However, you have the option to + perform a ``multi`` update as well as an ``upsert`` update. A + ``multi`` update updates multiple documents that meet the query + criteria. An :term:`upsert` update inserts a document if no document + in the collection matches the ``query`` criteria. + + + In version 2.2, the :method:`db.collection.update()` method can take an ``options`` :term:`document` as a parameter to specify the ``multi`` and the ``upsert`` options. However, the :method:`db.collection.update()` still supports the ``upsert`` and @@ -84,7 +85,7 @@ db.collection.update() criteria, insert a new document with the fields and values of the ``query`` and ``update``. - Starting in version 2.2, you can use the ``options`` + In version 2.2, you can use the ``options`` parameter instead of the ``upsert`` parameter. .. note:: @@ -104,85 +105,88 @@ db.collection.update() When ``true``, the :method:`db.collection.update()` method updates all documents that meet the ``query`` criteria. - Starting in version 2.2, you can use the ``options`` + In version 2.2, you can use the ``options`` parameter instead of the ``multi`` parameter. -Examples -~~~~~~~~ + Consider the following examples of the :method:`update() + ` method: -- To update specific fields in a single document, you can call the - :method:`db.collection.update()` method with the ``update`` parameter - consisting of :ref:`update operators ` expressions, - as in the following: + - To update specific fields in a single document, you can call the + :method:`db.collection.update()` method with the ``update`` + parameter consisting of :ref:`update operators ` + expressions, as in the following: - .. code-block:: javascript + .. code-block:: javascript - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } ) - This query will update in the ``products`` collection a single - document that matches the ``query`` criteria and set the value of the - field ``x`` to ``6`` and increment the value of the field ``y`` by - ``5``. All other fields of the modified document will remain the same. + This query will update in the ``products`` collection a single + document that matches the ``query`` criteria and set the value of + the field ``x`` to ``6`` and increment the value of the field + ``y`` by ``5``. All other fields of the modified document will + remain the same. -- To replace completely all the fields in a single document with those - in the ``update`` parameter, you can call the - :method:`db.collection.update()` method with the ``update`` parameter - consisting of ``key:value`` expressions, as in the following: + - To replace completely all the fields in a single document with + those in the ``update`` parameter, you can call the + :method:`db.collection.update()` method with the ``update`` + parameter consisting of ``key:value`` expressions, as in the + following: - .. code-block:: javascript + .. code-block:: javascript - db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) + db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } ) - This query will update in the ``products`` collection a single - document that matches the ``query`` criteria and set the value of the - field ``x`` to ``6`` and set the value of the field ``y`` to ``15``. - All other fields of the modified document will be **removed** other - than the :term:`_id` field. + This query will update in the ``products`` collection a single + document that matches the ``query`` criteria and set the value of + the field ``x`` to ``6`` and set the value of the field ``y`` to + ``15``. All other fields of the modified document will be + **removed** other than the :term:`_id` field. -- To update multiple documents, you can call the - :method:`db.collection.update()` method with the ``options`` - parameter specifying the ``multi`` option, as in the following: + - To update multiple documents, you can call the + :method:`db.collection.update()` method with the ``options`` + parameter specifying the ``multi`` option, as in the following: - .. 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 } }, { multi: true } ) - This query will update **all** documents in the ``products`` - collection that matches the ``query`` criteria, setting the value of - the field ``x`` to ``6`` and the value of the field ``y`` to ``15``. - All other fields in the updated documents remain unchanged. + This query will update **all** documents in the ``products`` + collection that matches the ``query`` criteria, setting the value + of the field ``x`` to ``6`` and the value of the field ``y`` to + ``15``. All other fields in the updated documents remain unchanged. - You can also perform the same update by calling the - :method:`db.collection.update()` method with the ``multi`` parameter: - - .. code-block:: javascript + You can also perform the same update by calling the + :method:`db.collection.update()` method with the ``multi`` + parameter: - db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true ) + .. code-block:: javascript -- To update a single document or to insert a new document if no - document matches the ``query`` criteria, you can call the - :method:`db.collection.update()` method with the ``options`` - parameter specifying the ``upsert`` option, as in the following: + db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true ) - .. code-block:: javascript - - db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } ) + - To update a single document or to insert a new document if no + document matches the ``query`` criteria, you can call the + :method:`db.collection.update()` method with the ``options`` + parameter specifying the ``upsert`` option, as in the following: - This query will either: + .. code-block:: javascript + + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: 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* + This query will either: - - 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``. + - 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* - You can also perform the same update by calling the - :method:`db.collection.update()` method with the ``upsert`` parameter: + - 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 + 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 } }, true ) + .. code-block:: javascript - \ No newline at end of file + db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, true )