DOCS-14795 update order numeric when possible

jmd-mongo · jeff-allen-mongo · commit 537c1f1e29aa · 2021-09-29T17:29:14.000-04:00
diff --git a/source/includes/fact-update-operator-processing-order.rst b/source/includes/fact-update-operator-processing-order.rst
@@ -0,0 +1,4 @@
+Starting in MongoDB 5.0, update operators process document fields with
+string-based names in lexicographic order. Fields with numeric names are
+processed in numeric order. See :ref:`Update Operators Behavior 
+<update-operators-processing-order>` for details.
diff --git a/source/reference/operator/update.txt b/source/reference/operator/update.txt
@@ -33,6 +33,30 @@ Specify the operator expression in a document of the form:
 Update Operators
 ----------------
 
+.. _update-operators-processing-order:
+
+Behavior
+~~~~~~~~
+
+Starting in MongoDB 5.0, update operators process document fields with
+string-based names in lexicographic order. Fields with numeric names are
+processed in numeric order. 
+
+In MongoDB 4.4 and earlier, update operators process all document fields 
+in lexicographic order. 
+
+Consider this example :update:`$set` command:
+
+.. code-block:: javascript
+ 
+  { $set: { "a.2": <new value>, "a.10": <new value>, } }
+
+In MongoDB 5.0 and later, ``"a.2"`` is processed before ``"a.10"`` 
+because ``2`` comes before ``10`` in numeric order. 
+
+In MongoDB 4.4 and earlier, ``"a.10"`` is processed before ``"a.2"`` 
+because ``10`` comes before ``2`` in lexicographic order. 
+
 Fields
 ~~~~~~
 
diff --git a/source/reference/operator/update/addToSet.txt b/source/reference/operator/update/addToSet.txt
@@ -30,6 +30,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 :update:`$addToSet` only ensures that there are no duplicate items
 *added* to the set and does not affect existing duplicate elements.
 :update:`$addToSet` does not guarantee a particular ordering of
diff --git a/source/reference/operator/update/bit.txt b/source/reference/operator/update/bit.txt
@@ -42,6 +42,8 @@ Behavior
 
 .. include:: /includes/extracts/update-operation-empty-operand-expressions-bit.rst
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt
@@ -41,6 +41,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field does not exist, :update:`$currentDate` adds the field to a
 document.
 
diff --git a/source/reference/operator/update/each.txt b/source/reference/operator/update/each.txt
@@ -37,6 +37,11 @@ Definition
    other modifiers. For a list of modifiers available for
    :update:`$push`, see :ref:`push-modifiers`.
 
+Behavior
+--------
+
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt
@@ -27,6 +27,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 The :update:`$inc` operator accepts positive and negative values.
 
 If the field does not exist, :update:`$inc` creates the field and sets
diff --git a/source/reference/operator/update/max.txt b/source/reference/operator/update/max.txt
@@ -32,6 +32,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field does not exists, the :update:`$max` operator sets the
 field to the specified value.
 
diff --git a/source/reference/operator/update/min.txt b/source/reference/operator/update/min.txt
@@ -30,6 +30,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field does not exist, the :update:`$min` operator sets the
 field to the specified value.
 
diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt
@@ -31,6 +31,8 @@ Behavior
 
 .. include:: /includes/extracts/update-operation-empty-operand-expressions-mul.rst
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 Missing Field
 ~~~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/pop.txt b/source/reference/operator/update/pop.txt
@@ -31,6 +31,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 The :update:`$pop` operation fails if the ``<field>`` is not an array.
 
 If the :update:`$pop` operator removes the last item in the
diff --git a/source/reference/operator/update/position.txt b/source/reference/operator/update/position.txt
@@ -58,6 +58,10 @@ Definition
      greater than or equal to the length of the array, the :update:`$push`
      adds elements to the beginning of the array.
 
+Behavior
+--------
+
+.. include:: /includes/fact-update-operator-processing-order.rst
 
 Examples
 --------
diff --git a/source/reference/operator/update/positional-all.txt b/source/reference/operator/update/positional-all.txt
@@ -43,6 +43,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/positional-filtered.txt b/source/reference/operator/update/positional-filtered.txt
@@ -52,6 +52,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/positional.txt b/source/reference/operator/update/positional.txt
@@ -59,6 +59,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/pull.txt b/source/reference/operator/update/pull.txt
@@ -26,6 +26,8 @@ $pull
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If you specify a ``<condition>`` and the array elements are embedded
 documents, :update:`$pull` operator applies the ``<condition>`` as if each
 array element were a document in a collection. See
diff --git a/source/reference/operator/update/pullAll.txt b/source/reference/operator/update/pullAll.txt
@@ -31,6 +31,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If a ``<value>`` to remove is a document or an array,
 :update:`$pullAll` removes only the elements in the array that match
 the specified ``<value>`` exactly, including order.
diff --git a/source/reference/operator/update/push.txt b/source/reference/operator/update/push.txt
@@ -28,6 +28,8 @@ Definition
 Behavior
 ---------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field is absent in the document to update, :update:`$push` adds
 the array field with the value as its element.
 
diff --git a/source/reference/operator/update/rename.txt b/source/reference/operator/update/rename.txt
@@ -37,6 +37,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 The :update:`$rename` operator logically performs an :update:`$unset`
 of both the old name and the new name, and then performs a
 :update:`$set` operation with the new name. As such, the operation may
diff --git a/source/reference/operator/update/set.txt b/source/reference/operator/update/set.txt
@@ -37,6 +37,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field does not exist, :update:`$set` will add a new field with the
 specified value, provided that the new field does not violate a type
 constraint.
diff --git a/source/reference/operator/update/setOnInsert.txt b/source/reference/operator/update/setOnInsert.txt
@@ -38,6 +38,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 .. include:: /includes/extracts/update-operation-empty-operand-expressions-set-on-insert.rst
 
 Example
diff --git a/source/reference/operator/update/slice.txt b/source/reference/operator/update/slice.txt
@@ -58,6 +58,8 @@ $slice
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 The order in which the modifiers appear is immaterial. Previous
 versions required the :update:`$each` modifier to appear as the first
 modifier if used in conjunction with :update:`$slice`. For a list of
diff --git a/source/reference/operator/update/sort.txt b/source/reference/operator/update/sort.txt
@@ -47,6 +47,8 @@ $sort
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 The :update:`$sort` modifier can sort array elements that are not
 documents. In previous versions, the :update:`$sort` modifier required
 the array elements be documents.
diff --git a/source/reference/operator/update/unset.txt b/source/reference/operator/update/unset.txt
@@ -36,6 +36,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 If the field does not exist, then :update:`$unset` does nothing (i.e.
 no operation).
 
diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt
@@ -232,6 +232,11 @@ operand expression ( ``{ }`` ):
 An empty update results in no changes and no :term:`oplog` entry is
 created (meaning that the operation is a no-op).
 
+Update Operator Processing Order
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-update-operator-processing-order.rst
+
 Aggregation Pipeline Operator Parameter Limits
 ----------------------------------------------
 
