DOCS-505 v2.2 has new update() API

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
-                 <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 <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()
-                  <db.collection.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 <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 <update-operators>` expressions such as the
+          :operator:`$set` operator expression, then:
+
+          - the ``update`` parameter must contain only :ref:`update
+            operators <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()
+   <db.collection.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 <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 )