In MongoDB, findOneAndReplace() replaces the first matching document (including embedded documents) and returns the original document by default, or the new one using options.
- Single-document replace: Replaces the first matching document.
- Returns original by default: Can return the new document with options.
- Filter-based: Uses a filter to find the document.
- Full replacement: Replaces the entire document (except _id).
- Supports embedded documents: Can replace nested content as part of the document.
- Transaction-safe: Can be used within multi-document transactions.
- Options supported: Control return behavior and other settings.
Syntax
db.collection.findOneAndReplace(filter, replacement, options)- filter: Criteria to find the document to replace.
- replacement: New document that replaces the matched document.
- options (optional): Additional settings for the operation.
- projection: Selects returned fields (1/true include, 0/false exclude).
- sort: Chooses which document to replace if multiple match.
- maxTimeMS: Sets a time limit (in ms) for the operation.
- upsert: Inserts a new document if no match is found when true.
- returnNewDocument: Returns the replaced document when true; otherwise returns the original (default).
- collation: Applies language-specific string comparison rules (case and accents).
Return Value of findOneAndReplace()
- Returns the original document by default.
- Returns the replaced document when returnDocument: 'after' is set.
Examples of MongoDB findOneAndReplace() Method
In the following examples, we are working with:
- Database: gfg
- Collection: student
- Document: Four documents contain name and the age of the students
Example 1: Replace first matching document and returns replaced document
Finds the first document where age is 18 and replaces it with a new document. It returns the original document before replacement.
Query:
db.student.findOneAndReplace({age:18},{name:"Maria", age:17})Before replacement:
After replacement:
Example 2: Replace the first matched document and returns a new document
Replaces a document where age is 25 and ensures that the updated document is returned instead of the original.
Query:
db.student.findOneAndReplace({age:25}, {name:"Sophia", age:45}, {returnDocument: "after"})Output:
Important Points
Here are some important points to remember:
- findOneAndReplace() finds and replaces the first document that matches the filter.
- Returns the original document by default; can return the updated document using returnDocument: 'after'.
- Supports options like projection, sort, maxTimeMS, upsert, returnDocument, and collation.
- Can be used for atomic single-document operations and within transactions.
