Skip to content

DOCS-64 document rename behavior when old name does not exist #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 4, 2012
Merged

DOCS-64 document rename behavior when old name does not exist #283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 110 additions & 45 deletions source/reference/command/findAndModify.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,68 +7,133 @@ findAndModify
.. dbcommand:: findAndModify

The :dbcommand:`findAndModify` command atomically modifies and
returns a single document. The shell and many :term:`drivers
<driver>` provide a :method:`findAndModify()` helper method. The
command has the following prototype form:
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 command has the following syntax:

.. code-block:: javascript

{ findAndModify: "collection", <options> }
{ findAndModify: <collection>, <options> }

The :dbcommand:`findAndModify` command takes the following are
sub-document ``options``:

:field document query:

Optional. Specifies the selection criteria for the
modification. The ``query`` field employs the same
:ref:`query selectors <query-selectors>` as used in the
:method:`db.collection.find()` method. Although the query may
match multiple documents, only one document will be selected
for the modification.

The ``query`` field has the following syntax:

.. code-block:: javascript

query: { <query expression> }

:field document sort:

Optional. Determines which document will be modified if the
query selects multiple documents. The first document as
determined by the ``sort`` will be the one modified.

The ``sort`` field has the following syntax:

.. code-block:: javascript

sort: { field1: value1, field2: value2, ... }

:field boolean remove:

Optional if ``update`` field exists. When ``true``, removes
the selected document. The default is ``false``.

The ``remove`` field has the following syntax:

.. code-block:: javascript

remove: <boolean>

Replace, ``collection`` with the name of the collection
containing the document that you want to modify, and specify
options, as a sub-document that specifies the following:
:field document update:

:field query: A query object. This statement might resemble the
:term:`document` passed to :method:`db.collection.find()`, and
should return *one* document from the database.
Optional if ``remove`` field exists. Performs an update of
the selected document. The ``update`` field employs the same
:ref:`update operators <update-operators>` or ``key:value``
specifications to modify the selected document.

:field sort: Optional. If the query selects multiple documents, the
first document given by this sort clause will be the
one modified.
.. code-block:: javascript

:field remove: When ``true``, :dbcommand:`findAndModify` removes
the selected document.
update: { <update expression> }

:field update: an :ref:`update operator <update-operators>` to
modify the selected document.
:field boolean new:

:field new: when ``true``, returns the modified document rather
than the original. :dbcommand:`findAndModify` ignores
the ``new`` option for ``remove`` operations.
Optional. When ``true``, returns the modified document rather
than the original. The :dbcommand:`findAndModify` method
ignores the ``new`` option for ``remove`` operations. The
default is ``false``.

:field fields: a subset of fields to return. See ":ref:`projection
operators <projection-operators>`" for more
information.
.. code-block:: javascript

:field upsert: when ``true``, creates a new document if the
specified ``query`` returns no documents. The
default is ``false``. The return value for these
operations is ``null`` in version 2.2
new: <boolean>

.. versionchanged:: 2.2
Previously, ``upsert`` operations returned a an empty document
(e.g. ``{ }``,) see :ref:`the 2.2 release notes
<2.2-findandmodify-returns-null>` for more information.
:field document fields:

Optional. A subset of fields to return.

.. code-block:: javascript

For example:
fields: { field1: <boolean>, field2: <boolean> ... }

:field boolean upsert:

Optional. Used in conjunction with the ``update`` field. When
``true``, the :dbcommand:`findAndModify` command creates a
new document if the ``query`` returns no documents. The
default is ``false``. In version 2.2, the
:dbcommand:`findAndModify` command returns ``null`` when
``upsert`` is ``true``.

.. code-block:: javascript

upsert: <boolean>

.. versionchanged:: 2.2
Previously, ``upsert`` operations returned a an empty
document (e.g. ``{ }``,) see :ref:`the 2.2 release notes
<2.2-findandmodify-returns-null>` for more information.

Consider the following example:

.. code-block:: javascript

{ findAndModify: "people",
{ query: { name: "Tom", state: "active", rating: { $gt: 10 } },
sort: { rating: 1 },
update: { $inc: { score: 1 } }
}
}

This operation, finds a document in the ``people`` collection
where the ``name`` field has the value ``Tom``, the
``active`` value in the ``state`` field and a value in the
``rating`` field :operator:`greater than <$gt>` 10. If there is
more than one result for this query, MongoDB sorts the results of
the query in descending order, and :operator:`increments <$inc>`
the value of the ``score`` field by 1. Using the shell helper,
query: { name: "Tom", state: "active", rating: { $gt: 10 } },
sort: { rating: 1 },
update: { $inc: { score: 1 } }
}

This command performs the following actions:

#. 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.

#. The ``sort`` orders the results of the query in ascending order.

#. The update :operator:`increments <$inc>` the value of the
``score`` field by 1.

#. The command returns the original (pre-modification) document
selected for this update.

The shell and many :term:`drivers <driver>` provide a
:method:`findAndModify()` helper method. Using the shell helper,
this same operation can take the following form:

.. code-block:: javascript
Expand Down
158 changes: 106 additions & 52 deletions source/reference/method/db.collection.findAndModify.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,98 @@ db.collection.findAndModify()

.. default-domain:: mongodb

.. method:: db.collection.findAndModify()

The :method:`db.collection.findAndModify()` method atomically modifies and
returns a single document. Always call :method:`db.collection.findAndModify()`
on a collection object, using the following form:

.. code-block:: javascript

db.collection.findAndModify();

Replace, ``collection`` with the name of the collection
containing the document that you want to modify, and specify
options, as a sub-document that specifies the following:

:field document query: A query object. This statement might
resemble the :term:`document` passed to
:method:`db.collection.find()`, and should return *one*
document from the database.

:field sort: Optional. If the query selects multiple documents, the
first document given by this sort clause will be the
one modified.

:field remove: Optional. When ``true``, :dbcommand:`findAndModify`
removes the selected document. The default is
``false``

:field update: An :ref:`update operator <update-operators>` to
modify the selected document.

:field new: Optional. When ``true``, returns the modified document
rather than the original. :dbcommand:`findAndModify`
ignores the ``new`` option for ``remove``
operations. The default is ``false``.

:field fields: Optional. A subset of fields to return. See
":ref:`projection operators <projection-operators>`"
for more information.

:field upsert: Optional. When ``true``, :dbcommand:`findAndModify`
creates a new document if the specified ``query``
returns no documents. The default is ``false``.

For example:
.. method:: db.collection.findAndModify

The :method:`db.collection.findAndModify()` method 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 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 <query-selectors>` as used in the
:method:`db.collection.find()` method. Although the query may
match multiple documents, only one document will be selected
for the modification.

The ``query`` field has the following syntax:

.. code-block:: javascript

query: { <query expression> }

:field document sort:

Optional. Determines which document will be modified if the
query selects multiple documents. The first document as
determined by the ``sort`` will be the one modified.

The ``sort`` field has the following syntax:

.. code-block:: javascript

sort: { field1: value1, field2: value2, ... }

:field boolean remove:

Optional if ``update`` field exists. When ``true``, removes
the selected document. The default is ``false``.

The ``remove`` field has the following syntax:

.. code-block:: javascript

remove: <boolean>

:field document update:

Optional if ``remove`` field exists. Performs an update of
the selected document. The ``update`` field employs the same
:ref:`update operators <update-operators>` or ``key:value``
specifications to modify the selected document.

.. code-block:: javascript

update: { <update expression> }

:field boolean new:

Optional. When ``true``, returns the modified document rather
than the original. The :dbcommand:`findAndModify` method
ignores the ``new`` option for ``remove`` operations. The
default is ``false``.

.. code-block:: javascript

new: <boolean>

:field document fields:

Optional. A subset of fields to return.

.. code-block:: javascript

fields: { field1: <boolean>, field2: <boolean> ... }

:field boolean upsert:

Optional. Used in conjunction with the ``update`` field. When
``true``, :dbcommand:`findAndModify` creates a new document
if the ``query`` returns no documents. The default is
``false``. In version 2.2, the :dbcommand:`findAndModify`
command returns ``null`` when ``upsert`` is ``true``.

.. code-block:: javascript

upsert: <boolean>

Consider the following example:

.. code-block:: javascript

Expand All @@ -57,14 +105,20 @@ db.collection.findAndModify()
update: { $inc: { score: 1 } }
} );

This operation finds a document in the ``people`` collection
where the ``name`` field has the value ``Tom``, the
``active`` value in the ``state`` field and a value in the
``rating`` field :operator:`greater than <$gt>` 10, and
:operator:`increments <$inc>` the value of the ``score`` field by
1. If there is more than one result for this query, MongoDB sorts
the results of the query in ascending order, and updates and
returns the first matching document found.
This command performs the following actions:

#. 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.

#. The ``sort`` orders the results of the query in ascending order.

#. The update :operator:`increments <$inc>` the value of the
``score`` field by 1.

#. The command returns the original (pre-modification) document
selected for this update.

.. warning::

Expand Down
Loading