- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.findOneAndUpdate()
db.collection.findOneAndUpdate()¶
On this page
Definition¶
-
db.collection.
findOneAndUpdate
(filter, update, options)¶ New in version 3.2.
Updates a single document based on the
filter
andsort
criteria.The
findOneAndUpdate()
method has the following form:The
findOneAndUpdate()
method takes the following parameters:Parameter Type Description filter
document The selection criteria for the update. The same query selectors as in the
find()
method are available.Specify an empty document
{ }
to update the first document returned in the collection.update
document The update document.
Must contain only update operators.
projection
document Optional. A subset of fields to return.
To return all fields in the returned document, omit this parameter.
sort
document Optional. Specifies a sorting order for the documents matched by the
filter
.See
cursor.sort()
.maxTimeMS
number Optional. Specifies a time limit in milliseconds within which the operation must complete within. Throws an error if the limit is exceeded. upsert
boolean Optional. When
true
,findOneAndUpdate()
either:- Creates a new document if no documents match the
filter
. For more details see upsert behavior. Returnsnull
after inserting the new document, unlessreturnNewDocument
istrue
. - Updates a single document that matches the
filter
.
To avoid multiple upserts, ensure that the
filter
fields are uniquely indexed.Defaults to
false
.returnNewDocument
boolean Optional. When
true
, returns the updated document instead of the original document.Defaults to
false
.Returns: Returns either the original document or, if returnNewDocument: true
, the updated document.- Creates a new document if no documents match the
Behavior¶
findOneAndUpdate()
updates the first matching
document in the collection that matches the filter
.
The sort
parameter can be used to influence which document is updated.
The projection
parameter takes a document in the following form:
The <boolean>
value can be any of the following:
1
ortrue
to include the field. The method returns the_id
field even if it is not explicitly stated in the projection parameter.0
orfalse
to exclude the field. This can be used on any field, including_id
.
Examples¶
Update A Document¶
The grades
collection contains documents similar to the following:
The following operation finds the first document where name : R. Stiles
and increments the score by 5
:
The operation returns the original document before the update:
If returnNewDocument
was true, the operation would return the
updated document instead.
Sort And Update A Document¶
The grades
collection contains documents similar to the following:
The following operation updates a document where name : "A. MacDyver"
. The
operation sorts the matching documents by points
ascending to update the
matching document with the least points.
The operation returns the original document before the update:
Project the Returned Document¶
The following operation uses projection to only display the _id
,
points
, and assignment
fields in the returned document:
The operation returns the original document with only the
fields specified in the projection
document and the _id
field as it was not
explicitly suppressed (_id: 0
) in the projection document.
Update Document with Time Limit¶
The following operation sets a 5ms time limit to complete the update:
If the operation exceeds the time limit, it returns:
Update Document with Upsert¶
The following operation uses the upsert
field to insert the update
document if nothing matches the filter
:
The operation returns the following:
If returnNewDocument
was false, the operation would return null
as
there is no original document to return.