diff --git a/source/includes/apiargs-dbcommand-findAndModify-lastErrorObject.yaml b/source/includes/apiargs-dbcommand-findAndModify-lastErrorObject.yaml new file mode 100644 index 00000000000..d1b8bd6a18c --- /dev/null +++ b/source/includes/apiargs-dbcommand-findAndModify-lastErrorObject.yaml @@ -0,0 +1,19 @@ +arg_name: field +name: updatedExisting +description: | + Contains ``true`` if an ``update`` operation modified an existing document. +interface: command +operation: findAndModify +optional: false +type: boolean +--- +arg_name: field +name: upserted +description: | + Contains the :ref:`objectid` of the inserted document if an ``update`` + operation with ``upsert: true`` resulted in a new document. +interface: command +operation: findAndModify +optional: false +type: document +... diff --git a/source/includes/apiargs-dbcommand-findAndModify-return.yaml b/source/includes/apiargs-dbcommand-findAndModify-return.yaml new file mode 100644 index 00000000000..70025c8bcaf --- /dev/null +++ b/source/includes/apiargs-dbcommand-findAndModify-return.yaml @@ -0,0 +1,30 @@ +arg_name: field +description: | + Contains the command's returned value. See :ref:`findandmodify-value-field` + for details. +interface: command +name: value +operation: findAndModify +optional: false +type: document +--- +arg_name: field +description: | + Contains information about updated documents. See + :ref:`findandmodify-lastErrorObject` for details. +interface: command +name: lastErrorObject +operation: findAndModify +optional: false +type: document +--- +arg_name: field +description: | + Contains the command's execution status. ``1`` on success, or ``0`` if an + error occurred. +interface: command +name: ok +operation: findAndModify +optional: false +type: number +... diff --git a/source/includes/extracts-fact-findandmodify-return.yaml b/source/includes/extracts-fact-findandmodify-return.yaml new file mode 100644 index 00000000000..7c110df02a0 --- /dev/null +++ b/source/includes/extracts-fact-findandmodify-return.yaml @@ -0,0 +1,34 @@ +ref: _fact-findandmodify-return +content: | + If the ``new`` parameter is not set or is ``false``: + + - the pre-modification document if the query matcches a document, + + - otherwise, ``null``. + + If ``new`` is ``true``: + + - the modified document if the query returns a match, + + - the inserted document if ``upsert: true`` and no document matches the query, + + - otherwise, ``null``. + + Prior to MongoDB 3.0, if ``new`` is not set or is ``false``, ``upsert: true``, + and there is a ``sort`` term, then {{op}} would yield an empty document + ``{}`` instead of ``null``. +--- +ref: fact-findandmodify-command-return +inherit: + file: extracts-fact-findandmodify-return.yaml + ref: _fact-findandmodify-return +replacement: + op: :dbcommand:`findAndModify` +--- +ref: fact-findandmodify-method-return +inherit: + file: extracts-fact-findandmodify-return.yaml + ref: _fact-findandmodify-return +replacement: + op: :method:`db.collection.findAndModify()` +... diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index ee27bcd62c3..9b3f3c375b2 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -45,49 +45,25 @@ Output The return document contains the following fields: -- The ``lastErrorObject`` field that returns the details of the - command: +.. include:: /includes/apiargs/dbcommand-findAndModify-return.rst - - The ``updatedExisting`` field **only** appears if the command - specifies an ``update`` or an ``update`` with ``upsert: true``; - i.e. the field does not appear for a ``remove``. +.. _findandmodify-lastErrorObject: - - The ``upserted`` field **only** appears if the ``update`` with the - ``upsert: true`` operation results in an insertion. - -- The ``value`` field that returns either: - - - the original (i.e. pre-modification) document if ``new`` is - false, or - - - the modified or inserted document if ``new: true``. - -- The ``ok`` field that returns the status of the command. - -.. note:: +``lastErrorObject`` +~~~~~~~~~~~~~~~~~~~ - If the :dbcommand:`findAndModify` finds no matching document, - then: +The ``lastErrorObject`` embedded document contains the following fields: - - for ``update`` or ``remove`` operations, ``lastErrorObject`` does - not appear in the return document and the ``value`` field holds a - ``null``. +.. include:: /includes/apiargs/dbcommand-findAndModify-lastErrorObject.rst - .. code-block:: javascript +.. _findandmodify-value-field: - { "value" : null, "ok" : 1 } +``value`` +~~~~~~~~~ - - for ``update`` with ``upsert: true`` operation that results in an - insertion, if the command also specifies ``new`` is ``false`` - **and** specifies a ``sort``, the return document has a - ``lastErrorObject``, ``value``, and ``ok`` fields, but the - ``value`` field holds an empty document ``{}``. +The ``value`` embedded document contains the following: - - for ``update`` with ``upsert: true`` operation that results in an - insertion, if the command also specifies ``new`` is ``false`` but - does **not** specify a ``sort``, the return document has a - ``lastErrorObject``, ``value``, and ``ok`` fields, but the - ``value`` field holds a ``null``. +.. include:: /includes/extracts/fact-findandmodify-command-return.rst Behavior -------- @@ -290,30 +266,7 @@ and returns a document with the following fields: command, including the field ``upserted`` that contains the ``ObjectId`` of the newly inserted document, and -- The ``value`` field that contains an empty document ``{}`` as the - original document because the command included the ``sort`` option: - -.. code-block:: sh - - { - "lastErrorObject" : { - "connectionId" : 1, - "updatedExisting" : false, - "upserted" : ObjectId("54f62c08c85d4472eadea26e"), - "n" : 1, - "syncMillis" : 0, - "writtenTo" : null, - "err" : null, - "ok" : 1 - }, - "value" : { - - }, - "ok" : 1 - } - -If the command did **not** include the ``sort`` option, the ``value`` field -would contain ``null``: +- The ``value`` field containing ``null``. .. code-block:: sh diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index 4b8da0272d8..31dfb070bc3 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/source/reference/method/db.collection.findAndModify.txt @@ -45,25 +45,10 @@ Definition Return Data ----------- -The :method:`~db.collection.findAndModify()` method returns either: -the pre-modification document or, if ``new: true`` is set, the -modified document. +The :method:`~db.collection.findAndModify()` method returns one of the +following: -.. note:: - - - If the query finds no document for ``update`` or ``remove`` - operations, :method:`~db.collection.findAndModify()` returns - ``null``. - - - If the query finds no document for an ``update`` with an - ``upsert`` operation, :method:`~db.collection.findAndModify()` - creates a new document. If ``new`` is ``false``, **and** the - ``sort`` option is **NOT** specified, the method returns ``null``. - - - If the query finds no document for an ``update`` with an - ``upsert`` operation, :method:`~db.collection.findAndModify()` - creates a new document. If ``new`` is ``false``, **and** a - ``sort`` option, the method returns an empty document ``{}``. +.. include:: /includes/extracts/fact-findandmodify-method-return.rst Behavior -------- @@ -181,11 +166,7 @@ This method performs the following actions: the method. If no document matched the ``query`` condition, the method - returns ``null``: - - .. code-block:: javascript - - null + returns ``null``. Upsert ~~~~~~ diff --git a/source/release-notes/3.0-compatibility.txt b/source/release-notes/3.0-compatibility.txt index ce646ea2c30..ca8b11c19cb 100644 --- a/source/release-notes/3.0-compatibility.txt +++ b/source/release-notes/3.0-compatibility.txt @@ -464,6 +464,17 @@ The minimum 3.0-compatible driver versions are: General Compatibility Changes ----------------------------- +``findAndModify`` Return Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In MongoDB 3.0, the return document of the :dbcommand:`findAndModify` command +has changed when executing ``update`` operatons where the ``query`` +matches no document, ``upsert: true``, and ``new: false``. + +Now the return document's ``value`` field will always contain ``null`` in this +case. Previously, it would instead contain an empty document ``{}`` if the +arguments included a ``sort`` term. + ``upsert:true`` with a Dotted ``_id`` Query ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~