- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.findOneAndReplace()
db.collection.findOneAndReplace()¶
On this page
Definition¶
-
db.collection.
findOneAndReplace
(filter, replacement, options)¶ New in version 3.2.
Modifies and replaces a single document based on the
filter
andsort
criteria.The
findOneAndReplace()
method has the following form:The
findOneAndReplace()
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 replace the first document returned in the collection.replacement
document The replacement document.
Cannot contain update operators.
The
<replacement>
document cannot specify an_id
value that differs from the replaced document.projection
document Optional. A subset of fields to return.
To return all fields in the matching 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. Throws an error if the limit is exceeded. upsert
boolean Optional. When
true
,findOneAndReplace()
either:- Inserts the document from the
replacement
parameter if no document matches thefilter
. Returnsnull
after inserting the new document, unlessreturnNewDocument
istrue
. - Replaces the document that matches the
filter
with thereplacement
document.
MongoDB will add the
_id
field to the replacement document if it is not specified in either thefilter
orreplacement
documents. If_id
is present in both, the values must be equal.To avoid multiple upserts, ensure that the
query
fields are uniquely indexed.Defaults to
false
.returnNewDocument
boolean Optional. When
true
, returns the replacement document instead of the original document.Defaults to
false
.Returns: Returns either the original document or, if returnNewDocument: true
, the replacement document.- Inserts the document from the
Behavior¶
findOneAndReplace()
replaces the first matching
document in the collection that matches the filter
.
The sort
parameter can be used to influence which document is modified.
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¶
Replace A Document¶
The scores
collection contains documents similar to the following:
The following operation finds a document with score
less than
20000
and replaces it:
The operation returns the original document that has been replaced:
If returnNewDocument
was true, the operation would return the replacement
document instead.
Although multiple documents meet the filter criteria,
db.collection.findOneAndReplace
replaces only one document.
Sort and Replace A Document¶
The scores
collection contains documents similar to the following:
By including ascending sort
order on the score
field, the
following example replaces the document with lowest score among the
matching documents:
The operation returns the original document that has been replaced:
See Replace A Document for the non-sorted result of this command.
Project Specific Fields in Return Document¶
The scores
collection contains documents similar to the following:
The following operation uses projection to only display the team
field in
the returned document:
The operation returns the original document with only the team
field:
Replace Document with Time Limit¶
The following operation sets a 5ms time limit to complete:
If the operation exceeds the time limit, it returns:
Replace Document with Upsert¶
The following operation uses the upsert
field to insert the replacement
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.