diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index d339df31a55..f52220a7759 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -4,46 +4,189 @@ 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 + 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. + + The default behavior of 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 + ``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. + + :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. + + **If** the ``update`` parameter consists only of ``field: + value`` expressions, then: + + - 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. + + :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. + + :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``. + + 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. + + In version 2.2, you can use the ``options`` + parameter instead of the ``multi`` parameter. + + 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: + + .. 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. + + - 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 )