- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.findAndModify()
db.collection.findAndModify()¶
On this page
Definition¶
-
db.collection.
findAndModify
(<document>)¶ 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. ThefindAndModify()
method is a shell helper around thefindAndModify
command.The
findAndModify()
method has the following form:The
db.collection.findAndModify()
method takes a document parameter with the following subdocument fields:Parameter Type Description query
document Optional. The selection criteria for the modification. The query
field employs the same query selectors as used in thedb.collection.find()
method. Although the query may match multiple documents,findAndModify()
will select only one document to modify.sort
document Optional. Determines which document the operation modifies if the query selects multiple documents. findAndModify()
modifies the first document in the sort order specified by this argument.remove
Boolean Must specify either the remove
or theupdate
field. Removes the document specified in thequery
field. Set this totrue
to remove the selected document . The default isfalse
.update
document Must specify either the remove
or theupdate
field in thefindAndModify()
method. Performs an update of the selected document. Theupdate
field employs the same update operators orfield: value
specifications to modify the selected document.new
Boolean Optional. When true
, returns the modified document rather than the original. ThefindAndModify()
method ignores thenew
option forremove
operations. The default isfalse
.fields
document Optional. A subset of fields to return. The fields
document specifies an inclusion of a field with1
, as in:fields: { <field1>: 1, <field2>: 1, ... }
. See projection.upsert
Boolean Optional. Used in conjunction with the update
field. Whentrue
,findAndModify()
creates a new document if thequery
returns no documents. The default isfalse
.
Return Data¶
The findAndModify()
method returns either:
the pre-modification document or, if new: true
is set, the
modified document.
Note
If the query finds no document for
update
orremove
operations,findAndModify()
returnsnull
.If the query finds no document for an
upsert
, operation,findAndModify()
performs an insert. Ifnew
isfalse
, and thesort
option is NOT specified, the method returnsnull
.Changed in version 2.2: Previously returned an empty document
{}
. See the 2.2 release notes for more information.If the query finds no document for an
upsert
,findAndModify()
performs an insert. Ifnew
isfalse
, and asort
option, the method returns an empty document{}
.
Behaviors¶
Upsert and Unique Index¶
When findAndModify()
includes the upsert:
true
option and the query field(s) is not uniquely indexed, the
method could insert a document multiple times in certain circumstances.
For instance, if multiple clients each invoke the 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.
In the following example, no document with the name Andy
exists,
and multiple clients issue the following command:
Then, if these clients’ findAndModify()
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 unique index on the
name
field. With the unique index in place, the multiple methods
would observe one of the following behaviors:
- Exactly one
findAndModify()
would successfully insert a new document. - Zero or more
findAndModify()
methods would update the newly inserted document. - Zero or more
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.
Sharded Collections¶
When using findAndModify
in a sharded
environment, the query
must contain the shard key for
all operations against the shard cluster for the sharded collections.
findAndModify
operations issued against mongos
instances for non-sharded collections function normally.
Examples¶
Update and Return¶
The following method updates and returns an existing document in the people collection where the document matches the query criteria:
This method performs the following actions:
The
query
finds a document in thepeople
collection where thename
field has the valueTom
, thestate
field has the valueactive
and therating
field has a valuegreater than
10.The
sort
orders the results of the query in ascending order. If multiple documents meet thequery
condition, the method will select for modification the first document as ordered by thissort
.The update
increments
the value of thescore
field by 1.The method returns the original (i.e. pre-modification) document selected for this update:
To return the modified document, add the
new:true
option to the method.If no document matched the
query
condition, the method returnsnull
:
Update and Insert¶
The following method includes the upsert: true
option to
insert a new document if no document matches the query
condition:
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:
If the method did not include a sort
option, the method returns
null
.
Update, Insert and Return New 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:
The method returns the newly inserted document:
Sort and Remove¶
By including a sort
specification on the rating
field, the
following example removes from the people
collection a single
document with the state
value of active
and the lowest
rating
among the matching documents:
The method returns the deleted document: