- Reference >
- Database Commands >
- Query and Write Operation Commands >
- findAndModify
findAndModify¶
On this page
Definition¶
-
findAndModify
¶ The
findAndModify
command 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.The command has the following syntax:
The
findAndModify
command takes the following fields:Field 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 only select 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. 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.When
true
,findAndModify
creates a new document if no document matches thequery
, or if documents match thequery
,findAndModify
performs an update. To avoid multiple upserts, ensure that thequery
fields are uniquely indexed.The default is
false
.findAndModify
string The collection against which to run the command.
Output¶
The return document contains the following fields:
- The
lastErrorObject
field that returns the details of the command:- The
updatedExisting
field only appears if the command specifies anupdate
or anupdate
withupsert: true
; i.e. the field does not appear for aremove
. - The
upserted
field only appears if theupdate
with theupsert: true
operation results in an insertion.
- The
- 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 original (i.e. pre-modification) document if
- The
ok
field that returns the status of the command.
Note
If the findAndModify
finds no matching document,
then:
for
update
orremove
operations,lastErrorObject
does not appear in the return document and thevalue
field holds anull
.for
update
withupsert: true
operation that results in an insertion, if the command also specifiesnew
isfalse
and specifies asort
, the return document has alastErrorObject
,value
, andok
fields, but thevalue
field holds an empty document{}
.for
update
withupsert: true
operation that results in an insertion, if the command also specifiesnew
isfalse
but does not specify asort
, the return document has alastErrorObject
,value
, andok
fields, but thevalue
field holds anull
.
Behavior¶
Upsert and Unique Index¶
When the findAndModify
command includes the upsert:
true
option and the query field(s) is not uniquely indexed, the
command could insert a document multiple times in certain circumstances.
Consider an example where no document with the name Andy
exists and
multiple clients issue the following command:
If all the commands finish the query
phase before any command
starts the modify
phase, and there is no unique index on the
name
field, the commands may each perform an upsert, creating
multiple duplicate documents.
To prevent the creation of multiple duplicate documents,
create a unique index on
the name
field. With the unique index in place, then the multiple
findAndModify
commands will exhibit one of the
following behaviors:
- Exactly one
findAndModify
successfully inserts a new document. - Zero or more
findAndModify
commands update the newly inserted document. - Zero or more
findAndModify
commands fail when they attempt to insert a duplicate. If the command fails due to a unique index constraint violation, you can retry the command. 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. findAndModify
operations issued against
mongos
instances for non-sharded collections function
normally.
Concurrency¶
This command obtains a write lock on the affected database and
will block other operations until it has completed; however,
typically the write lock is short lived and equivalent to other
similar update()
operations.
Comparisons with the update
Method¶
When updating a document, findAndModify
and the
update()
method operate differently:
By default, both operations modify a single document. However, the
update()
method with itsmulti
option can modify more than one document.If multiple documents match the update criteria, for
findAndModify
, you can specify asort
to provide some measure of control on which document to update.With the default behavior of the
update()
method, you cannot specify which single document to update when multiple documents match.By default,
findAndModify
method returns an object that contains the pre-modified version of the document, as well as the status of the operation. To obtain the updated document, use thenew
option.The
update()
method returns aWriteResult
object that contains the status of the operation. To return the updated document, use thefind()
method. However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.You cannot specify a write concern to
findAndModify
to override the default write concern whereas, starting in MongoDB 2.6, you can specify a write concern to theupdate()
method.
When modifying a single document, both findAndModify
and the
update()
method atomically update the
document. See Atomicity and Transactions for more
details about interactions and order of operations of these methods.
Examples¶
Update and Return¶
The following command updates an existing document in the people
collection where the document matches the query
criteria:
This command 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 command will select for modification the first document as ordered by thissort
.The
update
increments
the value of thescore
field by 1.The command returns a document with the following fields:
The
lastErrorObject
field that contains the details of the command, including the fieldupdatedExisting
which istrue
, andThe
value
field that contains the original (i.e. pre-modification) document selected for this update:
To return the modified document in the value
field, add the
new:true
option to the command.
If no document match the query
condition, the command
returns a document that contains null
in the value
field:
The mongo
shell and many drivers
provide a findAndModify()
helper method.
Using the shell helper, this previous operation can take the
following form:
However, the findAndModify()
shell helper
method returns only the unmodified document, or if new
is
true
, the modified document.
upsert: true
¶
The following findAndModify
command includes the upsert:
true
option for the update
operation to either update a matching
document or, if no matching document exists, create a new document:
If the command finds a matching document, the command performs an update.
If the command does not find a matching document, the update
with upsert: true operation results in an insertion
and returns a document with the following fields:
- The
lastErrorObject
field that contains the details of the command, including the fieldupserted
that contains theObjectId
of the newly inserted document, and - The
value
field that contains an empty document{}
as the original document because the command included thesort
option:
If the command did not include the sort
option, the value
field
would contain null
:
Return New Document¶
The following findAndModify
command includes both
upsert: true
option and the new:true
option. The command either
updates a matching document and returns the updated document or, if no
matching document exists, inserts a document and returns the newly
inserted document in the value
field.
In the following example, no document in the people
collection
matches the query
condition:
The command returns the newly inserted document in the value
field: