diff --git a/source/reference/method/db.collection.findAndModify-param.yaml b/source/reference/method/db.collection.findAndModify-param.yaml new file mode 100644 index 00000000000..ae582d814cc --- /dev/null +++ b/source/reference/method/db.collection.findAndModify-param.yaml @@ -0,0 +1,99 @@ +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: query +type: document +position: 1 +description: | + The selection criteria for the modification. The ``query`` field + employs the same :ref:`query selectors ` as used in + the :method:`db.collection.find()` method. Although the query may + match multiple documents, :method:`~db.collection.findAndModify()` + will select only one document to modify. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: sort +type: document +position: 2 +description: | + Determines which document the operation modifies if the query selects + multiple documents. :method:`~db.collection.findAndModify()` modifies + the first document in the sort order specified by this argument. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: remove +type: Boolean +position: 3 +description: | + Removes the document specified in the ``update`` field. Set this to + ``true`` to remove the selected document . The default is ``false``. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: update +type: document +position: 4 +description: | + Performs an update of the selected document. The ``update`` field + employs the same :ref:`update operators ` or + ``field: value`` specifications to modify the selected document. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: new +type: Boolean +position: 5 +description: | + When ``true``, returns the modified document rather than the original. + The :method:`~db.collection.findAndModify()` method ignores the + ``new`` option for ``remove`` operations. The default is ``false``. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: fields +type: document +position: 6 +description: | + A subset of fields to return. The ``fields`` document specifies an + inclusion of a field with ``1``, as in: ``fields: { : 1, + : 1, ... }``. See :ref:`projection `. +--- +object: + name: db.collection.findAndModify() + type: method +field: + optional: true + type: param +name: upsert +type: Boolean +position: 7 +description: | + Used in conjunction with the ``update`` field. When ``true``, + :method:`~db.collection.findAndModify()` creates a new document if the + ``query`` returns no documents. The default is ``false``. +... diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index 89467c88f7f..19b627cd587 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/source/reference/method/db.collection.findAndModify.txt @@ -8,15 +8,21 @@ db.collection.findAndModify() (possibly w modifications) to the command findAndModify.txt and vice versa +Definition +---------- + .. method:: db.collection.findAndModify - The :method:`~db.collection.findAndModify()` method atomically + Atomically modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the ``new`` option. The :method:`~db.collection.findAndModify()` method is a shell helper around the :dbcommand:`findAndModify` command. + The :method:`~db.collection.findAndModify()` method has the following + form: + .. code-block:: none db.collection.findAndModify( { @@ -32,194 +38,152 @@ db.collection.findAndModify() The :method:`db.collection.findAndModify()` method takes a document parameter with the following subdocument fields: - :field document query: - - Optional. Specifies the selection criteria for the - modification. The ``query`` field employs the same - :ref:`query selectors ` as used in the - :method:`db.collection.find()` method. Although the query may - match multiple documents, - :method:`~db.collection.findAndModify()` will only select one - document to modify. + .. include:: /reference/method/db.collection.findAndModify-param.rst - :field document sort: +Returns +------- - Optional. Determines which document the operation will modify - if the query selects multiple documents. - :method:`~db.collection.findAndModify()` will modify the - first document in the sort order specified by this argument. +The :method:`~db.collection.findAndModify()` method returns either: - :field boolean remove: +- the pre-modification document or, - Optional if ``update`` field exists. When ``true``, removes - the selected document. The default is ``false``. +- if the ``new: true`` option is set, the modified document. - :field document update: +.. note:: - Optional if ``remove`` field exists. Performs an update of - the selected document. The ``update`` field employs the same - :ref:`update operators ` or ``field: value`` - specifications to modify the selected document. + - If no document is found for the ``update`` or ``remove``, the + method returns ``null``. - :field boolean new: + - If no document is found for an ``upsert``, which means the + command performs an insert, and ``new`` is ``false``, **and** + the ``sort`` option is **NOT** specified, the method returns + ``null``. - Optional. When ``true``, returns the modified document rather - than the original. The - :method:`~db.collection.findAndModify()` method ignores the - ``new`` option for ``remove`` operations. The default is - ``false``. + .. versionchanged:: 2.2 + Previously returned an empty document ``{}``. See :ref:`the + 2.2 release notes <2.2-findandmodify-returns-null>` for more + information. - :field document fields: + - If no document is found for an ``upsert``, which means the + command performs an insert, and ``new`` is ``false``, **and** a + ``sort`` option is specified, the method returns an empty + document ``{}``. - Optional. A subset of fields to return. The ``fields`` - document specifies an inclusion of a field with ``1``, as in - the following: - - .. code-block:: javascript - - fields: { : 1, : 1, ... } - - See :ref:`projection `. +Examples +-------- - :field boolean upsert: +Update +~~~~~~ - Optional. Used in conjunction with the ``update`` field. When - ``true``, :method:`~db.collection.findAndModify()` creates a - new document if the ``query`` returns no documents. The - default is ``false``. +The following method updates an existing document in the people +collection where the document matches the query criteria: - The :method:`~db.collection.findAndModify()` method returns either: +.. code-block:: javascript - - the pre-modification document or, + db.people.findAndModify( { + query: { name: "Tom", state: "active", rating: { $gt: 10 } }, + sort: { rating: 1 }, + update: { $inc: { score: 1 } } + } ) - - if the ``new: true`` option is set, the modified document. +This method performs the following actions: - .. note:: +#. The ``query`` finds a document in the ``people`` collection + where the ``name`` field has the value ``Tom``, the ``state`` + field has the value ``active`` and the ``rating`` field has a + value :operator:`greater than <$gt>` 10. - - If no document is found for the ``update`` or ``remove``, the - method returns ``null``. +#. The ``sort`` orders the results of the query in ascending order. + If multiple documents meet the ``query`` condition, the method + will select for modification the first document as ordered by + this ``sort``. - - If no document is found for an ``upsert``, which means the - command performs an insert, and ``new`` is ``false``, **and** - the ``sort`` option is **NOT** specified, the method returns - ``null``. +#. The update :operator:`increments <$inc>` the value of the + ``score`` field by 1. - .. versionchanged:: 2.2 - Previously returned an empty document ``{}``. See :ref:`the - 2.2 release notes <2.2-findandmodify-returns-null>` for more - information. +#. The method returns the original (i.e. pre-modification) document + selected for this update: - - If no document is found for an ``upsert``, which means the - command performs an insert, and ``new`` is ``false``, **and** a - ``sort`` option is specified, the method returns an empty - document ``{}``. + .. code-block:: javascript - Consider the following examples: + { + "_id" : ObjectId("50f1e2c99beb36a0f45c6453"), + "name" : "Tom", + "state" : "active", + "rating" : 100, + "score" : 5 + } - - The following method updates an existing document in the people - collection where the document matches the query criteria: + To return the modified document, add the ``new:true`` option to + the method. - .. code-block:: javascript + If no document matched the ``query`` condition, the method + returns ``null``: - db.people.findAndModify( { - query: { name: "Tom", state: "active", rating: { $gt: 10 } }, - sort: { rating: 1 }, - update: { $inc: { score: 1 } } - } ) + .. code-block:: javascript - This method performs the following actions: + null - #. The ``query`` finds a document in the ``people`` collection - where the ``name`` field has the value ``Tom``, the ``state`` - field has the value ``active`` and the ``rating`` field has a - value :operator:`greater than <$gt>` 10. +Update and Insert +~~~~~~~~~~~~~~~~~ - #. The ``sort`` orders the results of the query in ascending order. - If multiple documents meet the ``query`` condition, the method - will select for modification the first document as ordered by - this ``sort``. +The following method includes the ``upsert: true`` option to +insert a new document if no document matches the ``query`` +condition: - #. The update :operator:`increments <$inc>` the value of the - ``score`` field by 1. +.. code-block:: javascript - #. The method returns the original (i.e. pre-modification) document - selected for this update: + db.people.findAndModify( { + query: { name: "Gus", state: "active", rating: 100 }, + sort: { rating: 1 }, + update: { $inc: { score: 1 } }, + upsert: true + } ) - .. code-block:: javascript +If the method does **not** find a matching document, the method +performs an upsert. Because the method included the ``sort`` +option, it returns an empty document ``{ }`` as the original +(pre-modification) document: - { - "_id" : ObjectId("50f1e2c99beb36a0f45c6453"), - "name" : "Tom", - "state" : "active", - "rating" : 100, - "score" : 5 - } - - To return the modified document, add the ``new:true`` option to - the method. - - If no document matched the ``query`` condition, the method - returns ``null``: +.. code-block:: javascript - .. code-block:: javascript + { } - null +If the method did **not** include a ``sort`` option, the method returns +``null``. - - The following method includes the ``upsert: true`` option to - insert a new document if no document matches the ``query`` - condition: +.. code-block:: javascript - .. code-block:: javascript + null - db.people.findAndModify( { - query: { name: "Gus", state: "active", rating: 100 }, - sort: { rating: 1 }, - update: { $inc: { score: 1 } }, - upsert: true - } ) +Update, Insert and Return Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If the method does **not** find a matching document, the method - performs an upsert. Because the method included the ``sort`` - option, it returns an empty document ``{ }`` as the original - (pre-modification) document: +The following method includes both the ``upsert: true`` option and +the ``new:true`` option to return the newly inserted document if a +document matching the ``query`` is not found: - .. code-block:: javascript +.. code-block:: none - { } + db.people.findAndModify( { + query: { name: "Pascal", state: "active", rating: 25 }, + sort: { rating: 1 }, + update: { $inc: { score: 1 } }, + upsert: true, + new: true + } ) - If the method did **not** include a ``sort`` option, the method returns - ``null``. +The method returns the newly inserted document: + +.. code-block:: javascript - .. code-block:: javascript - - null - - - The following method includes both the ``upsert: true`` option and - the ``new:true`` option to return the newly inserted document if a - document matching the ``query`` is not found: - - .. code-block:: none - - db.people.findAndModify( { - query: { name: "Pascal", state: "active", rating: 25 }, - sort: { rating: 1 }, - update: { $inc: { score: 1 } }, - upsert: true, - new: true - } - ) - - The method returns the newly inserted document: - - .. code-block:: javascript - - { - "_id" : ObjectId("50f49ad6444c11ac2448a5d6"), - "name" : "Pascal", - "rating" : 25, - "score" : 1, - "state" : "active" - } + { + "_id" : ObjectId("50f49ad6444c11ac2448a5d6"), + "name" : "Pascal", + "rating" : 25, + "score" : 1, + "state" : "active" + } When :method:`~db.collection.findAndModify()` includes the ``upsert: true`` option **and** the query field(s) is not uniquely indexed, the @@ -228,45 +192,49 @@ db.collection.findAndModify() method with the same ``query`` condition and these methods complete the ``find`` phase before any of methods perform the ``modify`` phase, these methods could insert the same document. - - Consider an example where no document with the name ``Andy`` exists - and multiple clients issue the following command: - .. code-block:: javascript +No Matching Document +~~~~~~~~~~~~~~~~~~~~ + +The following is an example where no document with the name ``Andy`` exists +and multiple clients issue the following command: + +.. code-block:: javascript + + db.people.findAndModify( { + query: { name: "Andy" }, + sort: { rating: 1 }, + update: { $inc: { score: 1 } }, + upsert: true + } ) + +Limitation +---------- + +If all the methods finish the ``query`` phase before any command +starts the ``modify`` phase, **and** there is no unique index on the +``name`` field, the commands may all perform an upsert. To prevent +this condition, create a :ref:`unique index ` on +the ``name`` field. With the unique index in place, the multiple +methods would observe one of the following behaviors: + +- Exactly one :method:`~db.collection.findAndModify()` would + successfully insert a new document. + +- Zero or more :method:`~db.collection.findAndModify()` methods + would update the newly inserted document. + +- Zero or more :method:`~db.collection.findAndModify()` methods + would fail when they attempted to insert a duplicate. If the + method fails due to a unique index constraint violation, you can + retry the method. Absent a delete of the document, the retry + should not fail. + +.. warning:: - db.people.findAndModify( - { - query: { name: "Andy" }, - sort: { rating: 1 }, - update: { $inc: { score: 1 } }, - upsert: true - } - ) - - If all the methods finish the ``query`` phase before any command - starts the ``modify`` phase, **and** there is no unique index on the - ``name`` field, the commands may all perform an upsert. To prevent - this condition, create a :ref:`unique index ` on - the ``name`` field. With the unique index in place, the multiple - methods would observe one of the following behaviors: - - - Exactly one :method:`~db.collection.findAndModify()` would - successfully insert a new document. - - - Zero or more :method:`~db.collection.findAndModify()` methods - would update the newly inserted document. - - - Zero or more :method:`~db.collection.findAndModify()` methods - would fail when they attempted to insert a duplicate. If the - method fails due to a unique index constraint violation, you can - retry the method. Absent a delete of the document, the retry - should not fail. - - .. warning:: - - - When using :dbcommand:`findAndModify` in a :term:`sharded - ` environment, the ``query`` must contain the - :term:`shard key` for all operations against the shard cluster. - :dbcommand:`findAndModify` operations issued against - :program:`mongos` instances for non-sharded collections - function normally. + - When using :dbcommand:`findAndModify` in a :term:`sharded + ` environment, the ``query`` must contain the + :term:`shard key` for all operations against the shard cluster. + :dbcommand:`findAndModify` operations issued against + :program:`mongos` instances for non-sharded collections + function normally.