- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.findOneAndReplace()
db.collection.findOneAndReplace()¶
On this page
Definition¶
Syntax¶
The findOneAndReplace()
method has the following
form:
Parameters and Options¶
The findOneAndReplace()
method takes the following
parameters and options:
Parameter | Type | Description |
---|---|---|
filter | document | The selection criteria for the update. The same query
selectors as in the Specify an empty document If unspecified, defaults to an empty document. Starting in MongoDB 3.4.23+, the operation errors if the query argument is not a document. |
replacement | document | The replacement document. Cannot contain update operators. The |
projection | document | Optional. A subset of fields to return. To return all fields in the matching document, omit this parameter. Starting in MongoDB 3.4.23+, the operation errors if the projection argument is not a document. |
sort | document | Optional. Specifies a sorting order for the documents matched by the Starting in MongoDB 3.4.23+, the operation errors if the sort argument is not a document. See |
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
MongoDB will add the To avoid multiple upserts, ensure that the Defaults to |
returnNewDocument | boolean | Optional. When Defaults to |
collation | document | Optional. Specifies the collation to use for the operation. Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax: When specifying collation, the If the collation is unspecified but the collection has a
default collation (see If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. New in version 3.4. |
Returns¶
Returns either the original document or, if returnNewDocument: true, the replacement document.
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¶
Create a sample scores
collection with the following documents:
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¶
Create a sample scores
collection with the following documents:
By including an ascending sort on
the score
field, the following example replaces the document with
the lowest score among the documents that match the filter:
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¶
Create a sample scores
collection with the following documents:
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 no document 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.
Specify Collation¶
New in version 3.4.
Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.
Create a sample myColl
collection with the following documents:
The following operation includes the collation option:
The operation returns the following document: