DOCS-505 update() method has new api

kay-kim · kay-kim · commit 931e4b9ef6fc · 2012-09-18T14:26:31.000-04:00
diff --git 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 <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 <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.
-
-            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 <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 <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 <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 )
+
+  
