DOCSP-36301 Move duplicate key exception info to upsert page (#6332) (#6507)

* WIP

* remove 4.2 info

* formatting

* formatting

* first draft of review edits

* edits

* tweaks

* edits

* formatting

* typo

* edit

* edits

* review edits

* formatting fix

* remove extra unique index links

Author: jeff-allen-mongo

source/core/retryable-writes.txt

@@ -16,9 +16,8 @@ Retryable Writes
 
 Retryable writes allow MongoDB drivers to automatically retry certain
 write operations a single time if they encounter network errors, or if
-they cannot find a healthy :term:`primary` in the
-:ref:`replica sets <replication>` or :ref:`sharded cluster
-<sharding-introduction>`. [#duplicate-key-update]_
+they cannot find a healthy :term:`primary` in the :ref:`replica set
+<replication>` or :ref:`sharded cluster <sharding-introduction>`.
 
 Prerequisites
 -------------
@@ -105,20 +104,15 @@ cannot be :writeconcern:`{w: 0} <\<number\>>`.
    * - | :method:`db.collection.insertOne()`
        | :method:`db.collection.insert()`
        | :method:`db.collection.insertMany()`
-
-     - Insert operations.
+     - Insert operations
 
    * - | :method:`db.collection.updateOne()`
        | :method:`db.collection.replaceOne()`
-       | :method:`db.collection.save()`
-       | :method:`db.collection.update()` where ``multi`` is ``false``
-
-     - Single-document update operations. [#duplicate-key-update]_
+     - Single-document update operations
 
    * - | :method:`db.collection.deleteOne()`
        | :method:`db.collection.remove()` where ``justOne`` is ``true``
-
-     - Single document delete operations.
+     - Single document delete operations
 
    * - | :method:`db.collection.findAndModify()`
        | :method:`db.collection.findOneAndDelete()`
@@ -165,16 +159,6 @@ cannot be :writeconcern:`{w: 0} <\<number\>>`.
    retryable write or in a :doc:`transaction </core/transactions>`. For
    details, see :ref:`update-shard-key`.
 
-.. [#duplicate-key-update]
-   
-   MongoDB 4.2 will retry certain single-document upserts
-   (update with ``upsert: true`` and ``multi: false``) that encounter a 
-   duplicate key exception. See :ref:`retryable-update-upsert` for 
-   conditions.
-
-   Prior to MongoDB 4.2, MongoDB would not retry upsert operations
-   that encountered a duplicate key error.
-
 Behavior
 --------
 
@@ -203,163 +187,6 @@ the failover period exceeds :urioption:`serverSelectionTimeoutMS`.
    applications starts responding (without a restart), the write
    operation may be retried and applied again.
 
-.. _retryable-update-upsert:
-
-Duplicate Key Errors on Upsert
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-MongoDB 4.2 will retry single-document upsert operations 
-(i.e ``upsert : true`` and ``multi : false``) that
-fail due to a duplicate key error *only if* the operation meets
-*all* of the following conditions:
-
-- The target collection has a unique index that caused the duplicate key 
-  error.
-
-- The update match condition is either:
-
-  - A single equality predicate 
-
-    ``{ "fieldA" : "valueA" }``, 
-
-    *or*
-
-  - a logical AND of equality predicates 
-
-    ``{ "fieldA" : "valueA", "fieldB" : "valueB" }``
-
-- The set of fields in the unique index key pattern matches the set
-  of fields in the update query predicate.
-
-- The update operation does not modify any of the fields in the
-  query predicate.
-
-The following table contains examples of upsert operations that
-the server can or cannot retry on a duplicate key error:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 30 40 30
-
-   * - Unique Index Key Pattern
-     - Update Operation
-     - Retryable
-
-   * - .. code-block:: javascript
-          :copyable: false
-
-          { _id : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { _id : ObjectId("1aa1c1efb123f14aaa167aaa") },
-            { $set : { fieldA : 25 } },
-            { upsert : true }
-          )
-     - Yes
-
-   * - .. code-block:: javascript
-          :copyable: false
-
-          { fieldA : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : { $in : [ 25 ] } },
-            { $set : { fieldB : "someValue" } },
-            { upsert : true }
-          )
-     - Yes
-
-   * - .. code-block:: javascript
-          :copyable: false
-
-          { 
-            fieldA : 1, 
-            fieldB : 1 
-          }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : 25, fieldB : "someValue" },
-            { $set : { fieldC : false } },
-            { upsert : true }
-          )
-     - Yes
-
-   * - .. code-block:: javascript
-          :copyable: false
-          
-          { fieldA : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : { $lte : 25 } },
-            { $set : { fieldC : true } },
-            { upsert : true }
-          )
-     - No
-
-       The query predicate on ``fieldA`` is not an equality
-
-   * - .. code-block:: javascript
-          :copyable: false
-
-          { fieldA : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : { $in : [ 25 ] } },
-            { $set : { fieldA : 20 } },
-            { upsert : true }
-          )
-     - No
-
-       The update operation modifies fields specified in the
-       query predicate.
-
-   * - .. code-block:: javascript
-          :copyable: false
-          
-          { _id : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : { $in : [ 25 ] } },
-            { $set : { fieldA : 20 } },
-            { upsert : true }
-          )
-     - No
-
-       The set of query predicate fields (``fieldA``) does not
-       match the set of index key fields (``_id``).
-
-   * - .. code-block:: javascript
-          :copyable: false
-          
-          { fieldA : 1 }
-     - .. code-block:: javascript
-          :copyable: false
-
-          db.collName.updateOne(
-            { fieldA : 25, fieldC : true },
-            { $set : { fieldD : false } },
-            { upsert : true }
-          )
-     - No
-
-       The set of query predicate fields (``fieldA``, ``fieldC``)
-       does not match the set of index key fields (``fieldA``).
-
-Prior to MongoDB 4.2, MongoDB retryable writes did not support
-retrying upserts which failed due to duplicate key errors.
-
 Diagnostics
 ~~~~~~~~~~~
 

source/includes/extracts-upsert-unique-index.yaml

@@ -1,39 +1,114 @@
 ref: _upsert-unique-index-base
 content: |
 
-   When using the {{upsert}} option with the {{command}}
-   {{commandOrMethod}}, **and not** using a :ref:`unique index
-   <index-type-unique>` on the query field(s), multiple
-   instances of {{aOrAn}} {{command}} operation with similar query
-   field(s) could result in duplicate documents being inserted in
-   certain circumstances.
+   Upserts can create duplicate documents, unless there is a
+   :ref:`unique index <index-type-unique>` to prevent duplicates.
 
    Consider an example where no document with the name ``Andy`` exists
    and multiple clients issue the following command at roughly the same
    time:
 
    {{codeExample}}
 
-   If all {{command}} operations finish the query phase
-   before any client successfully inserts data, **and** there is no
-   :ref:`unique index <index-type-unique>` on the ``name`` field, each
-   {{command}} operation may result in an insert, creating multiple
-   documents with ``name: Andy``.
-
-   To ensure that only one such document is created, and the other
-   {{command}} operations update this new document instead, create a
-   :ref:`unique index <index-type-unique>` on the ``name`` field. This
-   guarantees that only one document with ``name: Andy`` is permitted
-   in the collection.
-   
-   With this unique index in place, the multiple {{command}} operations
-   now exhibit the following behavior:
+   If all {{command}} operations finish the query phase before any
+   client successfully inserts data, **and** there is no unique index on
+   the ``name`` field, each {{command}} operation may result in an
+   insert, creating multiple documents with ``name: Andy``.
+
+   A unique index on the ``name`` field ensures that only one document
+   is created. With a unique index in place, the multiple {{command}}
+   operations now exhibit the following behavior:
 
    - Exactly one {{command}} operation will successfully insert a new
      document.
 
-   - All other {{command}} operations will update the newly-inserted
-     document, incrementing the ``score`` value.
+   - Other {{command}} operations either update the newly-inserted
+     document or fail due to a unique key collision.
+     
+     In order for other {{command}} operations to update the
+     newly-inserted document, **all** of the following conditions must
+     be met:
+
+     - The target collection has a unique index that would cause a
+       duplicate key error.
+
+     - The update operation is not ``updateMany`` or ``multi`` is
+       ``false``.
+
+     - The update match condition is either:
+
+       - A single equality predicate. For example ``{ "fieldA" : "valueA" }``
+
+       - A logical AND of equality predicates. For example ``{ "fieldA" :
+         "valueA", "fieldB" : "valueB" }``
+
+     - The fields in the equality predicate match the fields in the
+       unique index key pattern.
+
+     - The update operation does not modify any fields in the
+       unique index key pattern.
+
+   The following table shows examples of ``upsert`` operations that,
+   when a key collision occurs, either result in an update or fail.
+
+   .. list-table::
+      :header-rows: 1
+      :widths: 30 40 30
+
+      * - Unique Index Key Pattern
+        - Update Operation
+        - Result
+
+      * - .. code-block:: javascript
+             :copyable: false
+
+             { name : 1 }
+
+        - .. code-block:: javascript
+             :copyable: false
+
+             db.people.updateOne(
+                { name: "Andy" },
+                { $inc: { score: 1 } },
+                { upsert: true }
+             )
+        - The ``score`` field of the matched document is incremented by
+          1.
+
+      * - .. code-block:: javascript
+             :copyable: false
+
+             { name : 1 }
+
+        - .. code-block:: javascript
+             :copyable: false
+
+             db.people.updateOne(
+                { name: { $ne: "Joe" } },
+                { $set: { name: "Andy" } },
+                { upsert: true }
+              )
+              
+        - The operation fails because it modifies the field in the
+          unique index key pattern (``name``).
+
+      * - .. code-block:: javascript
+             :copyable: false
+             
+             { name : 1 }
+        - .. code-block:: javascript
+             :copyable: false
+
+             db.people.updateOne(
+               { name: "Andy", email: "[email protected]" },
+               { $set: { active: false } },
+               { upsert: true }
+             )
+        - The operation fails because the equality predicate fields
+          (``name``, ``email``) do not match the index key field
+          (``name``).
+
+
 
 ---
 ref: upsert-unique-index-findAndModify-command

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

@@ -987,9 +987,11 @@ with :method:`~db.collection.update()`.
          :method:`WriteResult()`
 
 .. _update-with-unique-indexes:
+.. _retryable-update-upsert:
+.. _upsert-duplicate-key-error:
 
-Upsert with Unique Index
-````````````````````````
+Upsert with Duplicate Values
+````````````````````````````
 
 .. include:: /includes/extracts/upsert-unique-index-update-method.rst
 
@@ -1488,4 +1490,3 @@ field:
 .. seealso::
 
    :method:`WriteResult.hasWriteError()`
-