The findOneAndReplace() method replaces the first matched document based on the given selection criteria. By default, this method returns the original document. To return the replacement document, set the value of the returnNewDocument option to true. It takes eight parameters, the first parameter is selection criteria and the second parameter is the replacement document. And the others are optional. Using this method you can also replace embedded documents. You can also use this method in multi-document transactions.
Syntax:
db.Collection_name.findOneAndReplace(
selection_criteria:<document>,
replacement: <document>,
{
projection: <document>,
sort: <document>,
maxTimeMS: <number>,
upsert: <boolean>,
returnNewDocument: <boolean>,
collation: <document>
})
Parameters:
- The first parameter is the selection criteria for replacing the document with the new document.
- The second parameter is the replacement document.
- The third parameter is optional.
Optional Parameters:
- projection: The type of this parameter is document. It determines which fields are returned to the matching documents. This document takes:
{ field1: <value1>, field2: <value2> ... }Here if the value of the field is 1/true then it specifies the inclusion of the field, or if the value of the field is 0/false then it specifies the exclusion of the field.
- sort: It determines which document the operation will modify if the query selects multiple documents. findOneAndReplace() will replace the first document in the sort order specified by this argument. The type of this parameter is document.
- maxTimeMS: The type of this parameter is number. It specifies the time limit in milliseconds within which the operation must complete. It throws an error if the time limit is exceeded.
- upsert: The default value of this parameter is false. If the value of this option is set to true and no document matches the given filter query, then this method creates a new document from the replacement parameter and returns null(after inserting a new document) unless the value of returnNewDocument option is set to true. Or if the value of this upsert option is set to true, then this method replaces the document that matches the given filter query with the replacement document.
- returnNewDocument: The type of this parameter is boolean. By default, this method returns the original document. To return the replacement document, use the returnNewDocument option and set its value to true.
- Collation: It specifies the use of the collation for operations. It allows users to specify the language-specific rules for string comparison like rules for lettercase and accent marks. The type of this parameter is a document.
Return:
By default, this method returns the original document. To return the replacement document, use the returnNewDocument option and set its value to true.
Examples:
In the following examples, we are working with:
Database: gfg
Collections: student
Document: Four documents contains name and the age of the students
- Replace the first matched document whose age is 17 and returns replaced document:
db.student.findOneAndReplace({age:17},{name:"Mihir", age:17})Here, we find a document that matches the given filter query(i.e., age:17) from the student collection and then replace the matched document with a new document(i.e., {name:”Mihir”, age:17}) using the findOneAndReplace() method. Here, this method returns the original document.
After replacement:
- Replace the first matched document whose age is 17 and returns a new document:
db.student.findOneAndReplace({age:17},{name:"Sagar", age:17},
{returnNewDocument:true})Here, we find a document that matches the given filter query(i.e., age:17) from the student collection and then replace the matched document with a new document(i.e., {name:”Sagar”, age:17}) using the findOneAndReplace() method. Here, this method returns the new document because the value of the returnNewDocument option is set to true.
After replacement: