DOCS-13822 permit empty update modifiers

npentrel · npentrel · commit e8e6cc797437 · 2021-03-04T12:52:47.000+01:00
diff --git a/source/includes/extracts-update-operations-base.yaml b/source/includes/extracts-update-operations-base.yaml
@@ -0,0 +1,7 @@
+ref: _update-operation-empty-operand-expressions
+content: |
+  Starting in MongoDB 5.0, :binary:`~bin.mongod` no longer raises an
+  error when you use an update operator like :update:`${{operator}}`
+  with an empty operand expression ( ``{ }`` ). An empty update results
+  in no changes and no :term:`oplog` entry is created (i.e. the
+  operation is a no-op).
diff --git a/source/includes/extracts-update-operations.yaml b/source/includes/extracts-update-operations.yaml
@@ -0,0 +1,105 @@
+ref: update-operation-empty-operand-expressions-add-to-set
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: addToSet
+---
+ref: update-operation-empty-operand-expressions-bit
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: bit
+---
+ref: update-operation-empty-operand-expressions-current-date
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: currentDate
+---
+ref: update-operation-empty-operand-expressions-inc
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: inc
+---
+ref: update-operation-empty-operand-expressions-max
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: max
+---
+ref: update-operation-empty-operand-expressions-min
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: min
+---
+ref: update-operation-empty-operand-expressions-mul
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: mul
+---
+ref: update-operation-empty-operand-expressions-pop
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: pop
+---
+ref: update-operation-empty-operand-expressions-pull
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: pull
+---
+ref: update-operation-empty-operand-expressions-pull-all
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: pullAll
+---
+ref: update-operation-empty-operand-expressions-push
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: push
+---
+ref: update-operation-empty-operand-expressions-rename
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: rename
+---
+ref: update-operation-empty-operand-expressions-set
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: set
+---
+ref: update-operation-empty-operand-expressions-set-on-insert
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: setOnInsert
+---
+ref: update-operation-empty-operand-expressions-unset
+source:
+  file: extracts-update-operations-base.yaml
+  ref: _update-operation-empty-operand-expressions
+replacement:
+  operator: unset
+...
diff --git a/source/reference/operator/update/addToSet.txt b/source/reference/operator/update/addToSet.txt
@@ -35,6 +35,8 @@ Behavior
 :update:`$addToSet` does not guarantee a particular ordering of
 elements in the modified set.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-add-to-set.rst
+
 Missing Field
 ~~~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/bit.txt b/source/reference/operator/update/bit.txt
@@ -37,6 +37,11 @@ Definition
       constructor to specify integers. See :ref:`shell-type-int` or
       :ref:`shell-type-long` for more information.
 
+Behavior
+--------
+
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-bit.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt
@@ -44,6 +44,8 @@ Behavior
 If the field does not exist, :update:`$currentDate` adds the field to a
 document.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-current-date.rst
+
 Example
 -------
 
diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt
@@ -37,6 +37,8 @@ generate an error.
 
 :update:`$inc` is an atomic operation within a single document.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-inc.rst
+
 Example
 -------
 
diff --git a/source/reference/operator/update/max.txt b/source/reference/operator/update/max.txt
@@ -35,6 +35,8 @@ Behavior
 If the field does not exists, the :update:`$max` operator sets the
 field to the specified value.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-max.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/min.txt b/source/reference/operator/update/min.txt
@@ -37,6 +37,8 @@ For comparisons between values of different types, such as a number and
 a null, :update:`$min` uses the :ref:`BSON comparison order
 <faq-dev-compare-order-for-BSON-types>`.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-min.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt
@@ -29,6 +29,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-mul.rst
+
 Missing Field
 ~~~~~~~~~~~~~
 
diff --git a/source/reference/operator/update/pop.txt b/source/reference/operator/update/pop.txt
@@ -36,6 +36,8 @@ The :update:`$pop` operation fails if the ``<field>`` is not an array.
 If the :update:`$pop` operator removes the last item in the
 ``<field>``, the ``<field>`` will then hold an empty array.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-pop.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/pull.txt b/source/reference/operator/update/pull.txt
@@ -39,6 +39,8 @@ If the specified ``<value>`` to remove is a document, :update:`$pull`
 removes only the elements in the array that have the exact same fields
 and values. The ordering of the fields can differ.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-pull.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/pullAll.txt b/source/reference/operator/update/pullAll.txt
@@ -35,6 +35,8 @@ 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.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-pull-all.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/push.txt b/source/reference/operator/update/push.txt
@@ -39,6 +39,8 @@ If the value is an array, :update:`$push` appends the whole array as a
 :ref:`example-push-each`. For a list of modifiers available for
 :update:`$push`, see :ref:`push-modifiers`.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-push.rst
+
 .. _push-modifiers:
 
 Modifiers
diff --git a/source/reference/operator/update/rename.txt b/source/reference/operator/update/rename.txt
@@ -55,6 +55,8 @@ rename these fields as well as move the fields in and out of embedded
 documents. :update:`$rename` does not work if these fields are in array
 elements.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-rename.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/set.txt b/source/reference/operator/update/set.txt
@@ -47,6 +47,8 @@ fulfill the dotted path to the field.
 If you specify multiple field-value pairs, :update:`$set` will update
 or create each field.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-set.rst
+
 Examples
 --------
 
diff --git a/source/reference/operator/update/setOnInsert.txt b/source/reference/operator/update/setOnInsert.txt
@@ -35,9 +35,14 @@ Definition
 
    .. include:: /includes/use-dot-notation.rst
 
-Example
+Behavior
 --------
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-set-on-insert.rst
+
+Example
+-------
+
 A collection named ``products`` contains no documents.
 
 Then, the following :method:`db.collection.update()` with :ref:`upsert:
diff --git a/source/reference/operator/update/unset.txt b/source/reference/operator/update/unset.txt
@@ -44,6 +44,8 @@ replaces the matching element with ``null`` rather than removing the
 matching element from the array. This behavior keeps consistent the
 array size and element positions.
 
+.. include:: /includes/extracts/update-operation-empty-operand-expressions-unset.rst
+
 Example
 -------
 
diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt
@@ -74,6 +74,32 @@ Read Concern `Snapshot` on Capped Collections
 
 .. include:: /includes/extracts/transactions-capped-collection-read-change.rst
 
+Update Operator Changes
+-----------------------
+
+Starting in MongoDB 5.0, :binary:`~bin.mongod` no longer raises
+an error when you use the following update operators with an empty
+operand expression ( ``{ }`` ):
+
+- :update:`$addToSet`
+- :update:`$bit`
+- :update:`$currentDate`
+- :update:`$inc`
+- :update:`$max`
+- :update:`$min`
+- :update:`$mul`
+- :update:`$pop`
+- :update:`$pull`
+- :update:`$pullAll`
+- :update:`$push`
+- :update:`$rename`
+- :update:`$set`
+- :update:`$setOnInsert`
+- :update:`$unset`
+
+An empty update results in no changes and no :term:`oplog` entry is
+created (i.e. the operation is a no-op).
+
 General Changes
 ---------------
 
