DOCS-7904 Added unique index warning on method pages with upsert para…

source/includes/apiargs-method-db.collection.findAndModify-param.yaml

@@ -75,23 +75,11 @@ type: document
 ---
 arg_name: param
 description: |
-  Used in conjunction with the ``update`` field.
-
-  When ``true``, |operation| either:
-
-  - Creates a new document if no documents match the ``query``. For more
-    details see :ref:`upsert behavior <upsert-behavior>`.
-
-  - Updates a single document that matches the ``query``.
-
-  To avoid multiple upserts, ensure that the ``query`` fields
-  are :ref:`uniquely indexed <index-type-unique>`.
-
-  The default is ``false``.
+  .. include:: /includes/extracts/findAndModify-behavior-method.rst
 interface: method
 name: upsert
 operation: db.collection.findAndModify
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 7
 type: boolean
 ---

source/includes/apiargs-method-db.collection.findOneAndReplace-param.yaml

@@ -71,24 +71,12 @@ type: number
 ---
 arg_name: param
 description: |
-  When ``true``, :method:`~db.collection.findOneAndReplace()` either:
-
-  - Inserts the document from the ``replacement`` parameter if no document matches the
-    ``filter``. Returns ``null`` after inserting the new document, unless
-    ``returnNewDocument`` is ``true``.
-
-  - Replaces the document that matches the ``filter`` with the ``replacement`` document.
-
-  MongoDB will add the ``_id`` field to the replacement document if it is not specified
-  in either the ``filter`` or ``replacement`` documents. If ``_id`` is present in both,
-  the values must be equal.
-
-  Defaults to ``false``.
+  .. include:: /includes/extracts/findOneAndReplace-behavior-method.rst
 
 interface: method
 name: upsert
 operation: db.collection.findOneAndReplace
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 6
 type: boolean
 ---

source/includes/apiargs-method-db.collection.findOneAndUpdate-param.yaml

@@ -71,24 +71,12 @@ type: number
 ---
 arg_name: param
 description: |
-   When ``true``, :method:`~db.collection.findOneAndUpdate()` creates a new 
-   document if no document matches the ``filter``. If a document matches the 
-   filter, the method performs an update.
-
-   The new document is created using the equality conditions from the 
-   ``filter`` with the modifications from the ``update`` document.
-
-   Comparison conditions like :query:`$gt` or :query:`$lt` are ignored.
-
-   Returns ``null`` after inserting the new document, unless 
-   ``returnNewDocument`` is ``true``.
-
-   Defaults to ``false``.
+   .. include:: /includes/extracts/findOneAndUpdate-behavior-method.rst
 
 interface: method
 name: upsert
 operation: db.collection.findOneAndUpdate
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 6
 type: boolean
 ---

source/includes/apiargs-method-db.collection.replaceOne-param.yaml

@@ -30,21 +30,12 @@ type: document
 ---
 arg_name: param
 description: |
-  When ``true``, :method:`~db.collection.replaceOne()` either:
-
-  - Inserts the document from the ``replacement`` parameter if no document matches the
-    ``filter``. 
-
-  - Replaces the document that matches the ``filter`` with the ``replacement`` document.
-
-  MongoDB will add the ``_id`` field to the replacement document if it is not specified
-  in either the ``filter`` or ``replacement`` documents. If ``_id`` is present in both,
-  the values must be equal.
+  .. include:: /includes/extracts/replaceOne-behavior-method.rst
 
 interface: method
 name: upsert
 operation: db.collection.replaceOne
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 3
 type: boolean
 ---

source/includes/apiargs-method-db.collection.updateMany-param.yaml

@@ -33,22 +33,12 @@ type: document
 ---
 arg_name: param
 description: |
-  When ``true``, if no documents match the ``filter``, a new document is 
-  created using the equality comparisons in ``filter`` with the modifications 
-  from ``update``.
-
-  :doc:`Comparison </reference/operator/query>` operations from the ``filter`` 
-  will not be included in the new document.
-
-  If the ``filter`` only has comparison operations, then only the 
-  modifications from the ``update`` will be applied to the new document.
-
-  See :ref:`updateMany-example-update-multiple-documents-with-upsert`
+  .. include:: /includes/extracts/updateMany-behavior-method.rst
 
 interface: method
 name: upsert
 operation: db.collection.updateMany
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 3
 type: boolean
 ---

source/includes/apiargs-method-db.collection.updateOne-param.yaml

@@ -33,22 +33,12 @@ type: document
 ---
 arg_name: param
 description: |
-  When ``true``, if no documents match the ``filter``, a new document is 
-  created using the equality comparisons in ``filter`` with the modifications 
-  from ``update``.
-
-  :doc:`Comparison </reference/operator/query>` operations from the ``filter`` 
-  will not be included in the new document.
-
-  If the ``filter`` only has comparison operations, then only the 
-  modifications from the ``update`` will be applied to the new document.
-
-  See :ref:`updateOne-example-update-with-upsert`
+  .. include:: /includes/extracts/updateOne-behavior-method.rst
 
 interface: method
 name: upsert
 operation: db.collection.updateOne
-optional: true
+optional: false # Set to false w/ "Optional" in extract due to giza issue
 position: 3
 type: boolean
 ---

source/includes/extracts-parameter-upsert.yaml

@@ -0,0 +1,104 @@
+# "Optional" added in manually instead of optional:true due to giza bug.
+ref: _update-single-upsert-behavior
+content: |
+   Optional. {{conjunction}}When ``true``, {{upsertMethod}} either: 
+
+   - Creates a new document if no documents match the ``{{queryOrFilter}}``.
+     For more details see :ref:`upsert behavior <upsert-behavior>`. {{returnNewDocument}}
+
+   - Updates a single document that matches the ``{{queryOrFilter}}``.
+
+   To avoid multiple upserts, ensure that the ``{{queryOrFilter}}`` fields
+   are :ref:`uniquely indexed <index-type-unique>`.
+
+   Defaults to ``false``.
+
+---
+ref: findAndModify-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _update-single-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.findAndModify()`"
+  queryOrFilter: query
+  conjunction: "Used in conjuction with the ``update`` field.
+
+
+"
+---
+ref: findOneAndUpdate-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _update-single-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.findOneAndUpdate()`"
+  queryOrFilter: filter
+  returnNewDocument: "Returns ``null`` after inserting the new document, unless
+    ``returnNewDocument`` is ``true``."
+---
+ref: updateOne-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _update-single-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.updateOne()`"
+  queryOrFilter: filter
+---
+ref: _update-multi-upsert-behavior
+content: |
+   Optional. When ``true``, {{upsertMethod}} either: 
+
+   - Creates a new document if no documents match the ``{{queryOrFilter}}``.
+     For more details see :ref:`upsert behavior <upsert-behavior>`.
+
+   - Updates documents that match the ``{{queryOrFilter}}``.
+
+   To avoid multiple upserts, ensure that the ``{{queryOrFilter}}`` fields
+   are :ref:`uniquely indexed <index-type-unique>`.
+
+   Defaults to ``false``.
+---
+ref: updateMany-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _update-multi-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.updateMany()`"
+  queryOrFilter: filter
+---
+ref: _replace-upsert-behavior
+content: |
+   Optional. When ``true``, {{upsertMethod}} either:
+
+   - Inserts the document from the ``replacement`` parameter if no document matches the
+     ``filter``. {{returnNewDocument}}
+
+   - Replaces the document that matches the ``filter`` with the ``replacement`` document.
+
+   MongoDB will add the ``_id`` field to the replacement document if it is not specified
+   in either the ``filter`` or ``replacement`` documents. If ``_id`` is present in both,
+   the values must be equal.
+
+   To avoid multiple upserts, ensure that the ``query`` fields
+   are :ref:`uniquely indexed <index-type-unique>`.
+
+   Defaults to ``false``.
+---
+ref: replaceOne-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _replace-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.replaceOne()`"
+  queryOrFilter: filter
+---
+ref: findOneAndReplace-behavior-method
+source:
+  file: extracts-parameter-upsert.yaml
+  ref: _replace-upsert-behavior
+replacement:
+  upsertMethod: ":method:`~db.collection.findOneAndReplace()`"
+  queryOrFilter: filter
+  returnNewDocument: "Returns ``null`` after inserting the new document, unless
+    ``returnNewDocument`` is ``true``."
+...

source/reference/method/db.collection.update.txt

@@ -134,6 +134,8 @@ The update creates the new document with either:
   operator <update-operators>` expressions. The update creates a base
   document from the equality clauses in the ``<query>`` parameter, and
   then applies the update expressions from the ``<update>`` parameter.
+  :doc:`Comparison </reference/operator/query>` operations from the
+  ``<query>`` will not be included in the new document.
 
 If ``upsert`` is ``true`` and there are documents that match the query
 criteria, :method:`~db.collection.update()` performs an update.