- Reference >
- JavaScript Methods >
- db.collection.findAndModify()
db.collection.findAndModify()¶
-
db.collection.
findAndModify
()¶ The
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 thenew
option. ThefindAndModify()
method is a shell helper around thefindAndModify
command.The
db.collection.findAndModify()
method takes a document parameter with the following subdocument fields:Fields: - query (document) – Optional. Specifies 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 only select one document to modify. - sort (document) – Optional. Determines which document the operation will modify
if the query selects multiple documents.
findAndModify()
will modify the first document in the sort order specified by this argument. - remove (boolean) – Optional if
update
field exists. Whentrue
, removes the selected document. The default isfalse
. - update (document) – Optional if
remove
field exists. 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 the following: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
.
The
findAndModify()
method returns either:- the pre-modification document or,
- if the
new: true
option is set, the modified document.
Note
If no document is found for the
update
orremove
, the method returnsnull
.If no document is found for an
upsert
, which means the command performs an insert, andnew
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 no document is found for an
upsert
, which means the command performs an insert, andnew
isfalse
, and asort
option is specified, the method returns an empty document{}
.
Consider the following examples:
The following method updates 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
:
The following method includes the
upsert: true
option to insert a new document if no document matches thequery
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 returnsnull
.The following method includes both the
upsert: true
option and thenew:true
option to return the newly inserted document if a document matching thequery
is not found:
The method returns the newly inserted document:
When
findAndModify()
includes theupsert: 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 samequery
condition and these methods complete thefind
phase before any of methods perform themodify
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:If all the methods finish the
query
phase before any command starts themodify
phase, and there is no unique index on thename
field, the commands may all perform an upsert. To prevent this condition, create a unique index on thename
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.
Warning
- When using
findAndModify
in a sharded environment, thequery
must contain the shard key for all operations against the shard cluster.findAndModify
operations issued againstmongos
instances for non-sharded collections function normally.
- query (document) – Optional. Specifies the selection criteria for the
modification. The