- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.findAndModify()
db.collection.findAndModify()¶
On this page
Definition¶
-
db.collection.
findAndModify
(document)¶ 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 embedded document 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 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
.
Return Data¶
For remove operations, if the query matches a document,
findAndModify()
returns the removed document.
If the query does not match a document to remove,
findAndModify()
returns null
.
For update operations, findAndModify()
returns
one of the following:
- If the
new
parameter is not set or isfalse
:- the pre-modification document if the query matches a document;
- otherwise,
null
.
- If
new
istrue
:- the modified document if the query returns a match;
- the inserted document if
upsert: true
and no document matches the query; - otherwise,
null
.
Changed in version 3.0: In previous versions, if for the update, sort
is specified,
and upsert: true
, and the new
option is not set or new:
false
, db.collection.findAndModify()
returns an empty document {}
instead of null
.
Behavior¶
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.
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, 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, the multiple methods
will exhibit one of the following behaviors:
- Exactly one
findAndModify()
successfully inserts a new document. - Zero or more
findAndModify()
methods update the newly inserted document. - Zero or more
findAndModify()
methods fail when they attempt 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.
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 the pre-modified version of the document. 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 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
.
Upsert¶
The following method 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 method finds a matching document, the method performs an update.
If the method does not find a matching document, the method creates
a new document. 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
.
Return New Document¶
The following method includes both the upsert: true
option and the
new:true
option. The method 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 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: