DOCSP-20026 updates for update pt6 v5.2 (#136) (#139)

* DOCSP-20026 updates for update pt6

* Add mul

* Still in mul

* Add files

* Add files

* Add files

* Staging updates

* Review updates

* Staging tweaks

Author: Dave

source/includes/example-addToSet-each.rst

@@ -15,8 +15,8 @@ with the :update:`$each` modifier to add multiple elements to the
       { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
     )
 
-The operation adds only ``"camera"`` and ``"accessories"`` to the
-``tags`` array since ``"electronics"`` already exists in the array:
+The operation only adds ``"camera"`` and ``"accessories"`` to the
+``tags`` array. ``"electronics"`` was already in the array:
 
 .. code-block:: javascript
 

source/includes/example-push-with-multiple-modifiers.rst

@@ -41,7 +41,7 @@ The following :update:`$push` operation uses:
       }
    )
 
-The result of the operation is keep only the three highest scoring quizzes:
+After the operation only the three highest scoring quizzes are in the array:
 
 .. code-block:: javascript
 

source/reference/operator/query/and.txt

@@ -90,7 +90,7 @@ The query cannot use an implicit ``AND`` operation because it uses the
 .. seealso::
 
    - :method:`~db.collection.find()`
-   - :method:`~db.collection.update()`
+   - :method:`~db.collection.updateMany()`
    - :query:`$ne`
    - :query:`$exists`
    - :update:`$set`

source/reference/operator/query/in.txt

@@ -16,12 +16,12 @@ $in
    of a field equals any value in the specified array. To specify an
    :query:`$in` expression, use the following prototype:
 
-   .. include:: /includes/fact-comparison-order.rst
-
    .. code-block:: javascript
 
       { field: { $in: [<value1>, <value2>, ... <valueN> ] } }
 
+   .. include:: /includes/fact-comparison-order.rst
+
    If the ``field`` holds an array, then the :query:`$in` operator
    selects the documents whose ``field`` holds an array that contains
    at least one element that matches a value in the specified array
@@ -36,43 +36,78 @@ $in
 Examples
 --------
 
+Create the ``inventory`` collection:
+
+.. code-block:: javascript
+
+   db.inventory.insertMany( [
+      { "item": "Pens", "quantity": 350, "tags": [ "school", "office" ] },
+      { "item": "Erasers", "quantity": 15, "tags": [ "school", "home" ] },
+      { "item": "Maps", "tags": [ "office", "storage" ] },
+      { "item": "Books", "quantity": 5, "tags": [ "school", "storage", "home" ] }
+   ] )
+
 Use the ``$in`` Operator to Match Values
-----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Consider the following example:
 
 .. code-block:: javascript
 
-   db.inventory.find( { qty: { $in: [ 5, 15 ] } } )
+   db.inventory.find( { quantity: { $in: [ 5, 15 ] } }, { _id: 0 } )
+
+This query selects all documents in the ``inventory`` collection where
+the value of the ``quantity`` field is either 5 or 15. 
 
-This query selects all documents in the ``inventory``
-collection where the ``qty`` field value is either ``5`` or
-``15``. Although you can express this query using the
-:query:`$or` operator, choose the :query:`$in` operator rather
-than the :query:`$or` operator when performing equality checks on
-the same field.
+.. code-block:: javascript
+
+   { item: 'Erasers', quantity: 15, tags: [ 'school', 'home' ] },
+   { item: 'Books', quantity: 5, tags: [ 'school', 'storage', 'home' ] }
+
+Although you can write this query using the :query:`$or` operator,
+use the :query:`$in` operator rather than the :query:`$or` operator
+when performing equality checks on the same field.
 
 Use the ``$in`` Operator to Match Values in an Array
-----------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The collection ``inventory`` contains documents that include the field
-``tags``, as in the following:
+The following :method:`~db.collection.updateMany()` operation sets the
+``exclude`` field to ``false`` when the ``tags`` array has at least one
+element that matches either ``"home"`` or ``"school"``.
 
 .. code-block:: javascript
 
-   { _id: 1, item: "abc", qty: 10, tags: [ "school", "clothing" ], sale: false }
+   db.inventory.updateMany(
+      { tags: { $in: [ "home", "school" ] } },
+      { $set: { exclude: false } }
+   )
 
-Then, the following :method:`~db.collection.update()` operation will
-set the ``sale`` field value to ``true`` where the ``tags`` field holds
-an array with at least one element matching either ``"appliances"`` or
-``"school"``.
+Example output:
 
 .. code-block:: javascript
 
-   db.inventory.update(
-                        { tags: { $in: ["appliances", "school"] } },
-                        { $set: { sale:true } }
-                      )
+   {
+      item: 'Pens',
+      quantity: 350,
+      tags: [ 'school', 'office' ],
+      exclude: false
+    },
+    {
+      item: 'Erasers',
+      quantity: 15,
+      tags: [ 'school', 'home' ],
+      exclude: false
+    },
+    {
+      item: 'Maps',
+      tags: [ 'office', 'storage' ]
+    },
+    {
+      item: 'Books',
+      quantity: 5,
+      tags: [ 'school', 'storage', 'home' ],
+      exclude: false
+    }
 
 .. include:: /includes/extracts/additional-examples-arrays.rst
 
@@ -99,7 +134,8 @@ the ``tags`` field holds either a string that starts with ``be`` or
 .. seealso::
 
    - :method:`~db.collection.find()`
-   - :method:`~db.collection.update()`
+   - :method:`~db.collection.updateMany()`
    - :query:`$or`
    - :update:`$set`
    - :query:`$elemMatch`
+

source/reference/operator/query/nin.txt

@@ -12,47 +12,75 @@ $nin
 
 .. query:: $nin
 
-   *Syntax*: ``{ field: { $nin: [ <value1>, <value2> ... <valueN> ]} }``
+*Syntax*: ``{ field: { $nin: [ <value1>, <value2> ... <valueN> ] } }``
 
-   :query:`$nin` selects the documents where:
+:query:`$nin` selects the documents where:
 
-   - the ``field`` value is not in the specified ``array`` **or**
-   - the ``field`` does not exist.
+- the ``field`` value is not in the specified ``array`` **or**
+- the ``field`` does not exist.
 
-   .. include:: /includes/fact-comparison-order.rst
+If the ``field`` holds an array, then the :query:`$nin` operator selects
+the documents whose ``field`` holds an array with **no** element equal to
+a value in the specified array (for example, ``<value1>``,
+``<value2>``, and so on).
 
-   Consider the following query:
+.. include:: /includes/fact-comparison-order.rst
 
-   .. code-block:: javascript
+Examples
+--------
 
-      db.inventory.find( { qty: { $nin: [ 5, 15 ] } } )
+Create the ``inventory`` collection:
 
-   This query will select all documents in the ``inventory`` collection
-   where the ``qty`` field value does **not** equal ``5`` nor
-   ``15``. The selected documents will include those documents that do
-   *not* contain the ``qty`` field.
+.. code-block:: javascript
 
-   If the ``field`` holds an array, then the :query:`$nin` operator
-   selects the documents whose ``field`` holds an array with **no**
-   element equal to a value in the specified array (e.g. ``<value1>``,
-   ``<value2>``, etc.).
+   db.inventory.insertMany( [
+      { "item": "Pens", "quantity": 350, "tags": [ "school", "office" ] },
+      { "item": "Erasers", "quantity": 15, "tags": [ "school", "home" ] },
+      { "item": "Maps", "tags": [ "office", "storage" ] },
+      { "item": "Books", "quantity": 5, "tags": [ "school", "storage", "home" ] }
+   ] )
 
-   Consider the following query:
+Select on Unmatching Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   .. code-block:: javascript
+The following query selects all documents from the ``inventory``
+collection where the ``quantity`` does **not** equal either 5 or 15. 
 
-      db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } )
+The query also matches documents that do *not* have a ``quantity``
+field.
 
-   This :method:`~db.collection.update()` operation will set
-   the ``sale`` field value in the ``inventory`` collection where the
-   ``tags`` field holds an array with **no** elements matching an
-   element in the array ``["appliances", "school"]`` or where a
-   document does not contain the ``tags`` field.
+.. code-block:: javascript
 
-   .. include:: /includes/extracts/nin_operators_selectivity.rst
-      
-   .. seealso::
+   db.inventory.find( { quantity: { $nin: [ 5, 15 ] } }, { _id: 0 } )
+
+Example output:
+
+.. code-block:: javascript
+
+  { item: 'Pens', quantity: 350, tags: [ 'school', 'office' ] },
+  { item: 'Maps', tags: [ 'office', 'storage' ] }
+
+Select on Elements Not in an Array
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set the ``exclude`` field to ``true`` for documents that don't have the
+``"school"`` tag.
+
+.. code-block:: javascript
+
+   db.inventory.updateMany(
+       { tags: { $nin: [ "school" ] } },
+       { $set: { exclude: true } }
+   )
+
+:method:`~db.collection.updateMany()` also selects a document when the
+document does not contain the field :query:`$nin` is matching on.
+
+.. include:: /includes/extracts/nin_operators_selectivity.rst
+   
+.. seealso::
+
+   - :method:`~db.collection.find()`
+   - :method:`~db.collection.updateMany()`
+   - :update:`$set`
 
-      - :method:`~db.collection.find()`
-      - :method:`~db.collection.update()`
-      - :update:`$set`

source/reference/operator/update.txt

@@ -12,8 +12,8 @@ Update Operators
 
 .. _update-operators-top-level:
 
-The following modifiers are available for use in update operations;
-e.g. in :method:`db.collection.update()` and
+The following modifiers are available for use in update operations,
+for example, in :method:`db.collection.updateMany()` and
 :method:`db.collection.findAndModify()`.
 
 Specify the operator expression in a document of the form:

source/reference/operator/update/addToSet.txt

@@ -42,29 +42,30 @@ elements in the modified set.
 Missing Field
 ~~~~~~~~~~~~~
 
-If you use :update:`$addToSet` on a field that is absent in the document to
-update, :update:`$addToSet` creates the array field with the specified
-value as its element.
+If you use :update:`$addToSet` on a field that is absent from the
+document to update, :update:`$addToSet` creates the array field with
+the specified value as its element.
 
 Field is Not an Array
 ~~~~~~~~~~~~~~~~~~~~~~
 
 If you use :update:`$addToSet` on a field that is **not** an array, the
-operation will fail. For example, consider a document in a collection
-``foo`` that contains a non-array field ``colors``.
+operation will fail. 
+
+For example, create the ``pigments`` collection:
 
 .. code-block:: javascript
 
-   { _id: 1, colors: "blue,green,red" }
+   db.pigments.insertOne( { _id: 1, colors: "blue, green, red" } )
 
-The following :update:`$addToSet` operation on the non-array field
-``colors`` fails:
+The ``colors`` field is not an array. The following :update:`$addToSet`
+operation fails:
 
 .. code-block:: javascript
 
-   db.foo.update(
+   db.pigments.updateOne(
       { _id: 1 },
-      { $addToSet: { colors: "c" } }
+      { $addToSet: { colors: "mauve" } }
    )
 
 Value to Add is An Array
@@ -73,29 +74,27 @@ Value to Add is An Array
 If the value is an array, :update:`$addToSet` appends the whole array
 as a *single* element.
 
-Consider a document in a collection ``test`` containing an array
-field ``letters``:
+Create the ``alphabet`` collection:
 
 .. code-block:: javascript
 
-   { _id: 1, letters: ["a", "b"] }
+   db.alphabet.insertOne( { _id: 1, letters: ["a", "b"] } )
 
 The following operation appends the array ``[ "c", "d" ]`` to the
 ``letters`` field:
 
 .. code-block:: javascript
 
-   db.test.update(
+   db.alphabet.updateOne(
       { _id: 1 },
       { $addToSet: { letters: [ "c", "d" ] } }
    )
 
-The ``letters`` array now includes the ``[ "c", "d" ]`` array
-as an element:
+The array ``[ "c", "d" ]`` is added as a single element:
 
 .. code-block:: javascript
 
-   { _id: 1, letters: [ "a", "b", [ "c", "d" ] ] }
+    { _id: 1, letters: [ 'a', 'b', [ 'c', 'd' ] ] }
 
 .. tip::
 
@@ -117,11 +116,13 @@ duplicate of an existing array element.
 Examples
 --------
 
-Consider a collection ``inventory`` with the following document:
+Create the ``inventory`` collection:
 
 .. code-block:: javascript
 
-   { _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] }
+   db.inventory.insertOne( 
+      { _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] }
+   )
 
 Add to Array
 ~~~~~~~~~~~~
@@ -131,20 +132,20 @@ The following operation adds the element ``"accessories"`` to the
 
 .. code-block:: javascript
 
-   db.inventory.update(
+   db.inventory.updateOne(
       { _id: 1 },
       { $addToSet: { tags: "accessories" } }
    )
 
 Value Already Exists
 ~~~~~~~~~~~~~~~~~~~~
 
-The following :update:`$addToSet` operation has no effect as
+The following :update:`$addToSet` operation has no effect because
 ``"camera"`` is already an element of the ``tags`` array:
 
 .. code-block:: javascript
 
-   db.inventory.update(
+   db.inventory.updateOne(
       { _id: 1 },
       { $addToSet: { tags: "camera"  } }
    )
@@ -163,7 +164,8 @@ field.
 
 .. seealso::
 
-   - :method:`db.collection.update()`
+   - :method:`db.collection.updateMany()`
    - :method:`db.collection.findAndModify()`
    - :update:`$push`
    - :update:`$pull`
+