findOneAndReplace() (Replace and Return a Document)
Last updated: 2026-10-09
findOneAndReplace() (Replace and Return a Document)
findOneAndReplace() swaps the first document matching a filter for a replacement document and returns the document before or after the swap, e.g. `db.users.findOneAndReplace({ name: 'Bob' }, { name: 'Bob', age: 26 }, { returnDocument: 'after' })`. Unlike replaceOne(), it reads the document back, fitting flows that need the replacement result. Every field except _id is overwritten.
| Category | Write |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
db.<collection>.findOneAndReplace(<filter>, <replacement>, { returnDocument: 'after', upsert: <bool> })⚙️ Parameters
| filter | Predicate matching the document to replace. |
|---|---|
| new document | The full replacement; overwrites all fields except _id. |
| returnDocument | Optional. 'before' or 'after'; default 'before'. |
Returns：The document before (or after) replacement; null if nothing matched and upsert is off.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// findOneAndReplace: swap Bob's doc, return the new one
const doc = db.users.findOneAndReplace(
{ name: 'Bob' }, { name: 'Bob', age: 26, vip: true },
{ returnDocument: 'after' }
)
docOutput：
{
_id: ObjectId('64c8a1b20000000000000002'),
name: 'Bob',
age: 26,
vip: true
}📌 Notes
- The replacement must keep the original _id or an error is thrown
- The returned _id is always the original one (even when upsert inserts)
- Replacement overwrites wholesale — make sure the new document carries every field you need
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat is the difference between findOneAndReplace and replaceOne?
AreplaceOne() returns counters; findOneAndReplace() returns the document before or after the swap.
QCan findOneAndReplace change the _id?
ANo — the replacement must keep the original _id or the operation errors.
QWhat does findOneAndReplace return with upsert on?
AWhen nothing matches, a new document is inserted and returned, carrying the freshly generated _id.
