$replaceWith (Replace With)
Last updated: 2026-10-09
$replaceWith (Replace With)
$replaceWith is like $replaceRoot but tolerates null or missing expression results, keeping the original document instead of failing. It fits promote-if-possible scenarios. Everything else matches $replaceRoot semantics.
| Category | Core Stages |
|---|---|
| MongoDB Version | 4.2+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $replaceWith: <document expression> }⚙️ Parameters
| document expression | Expression whose result replaces the document; may be null or missing. |
|---|
Returns：Replaced document stream (original kept when result is null)
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $replaceWith: promote detail when present
db.orders.aggregate([
{ $replaceWith: '$detail' }
])Output：
// Orders with detail output it; others pass through unchanged📌 Notes
- Null or missing results keep the original document; $replaceRoot would error
- Takes an expression directly, while $replaceRoot wraps it in newRoot
- Often combined with $mergeObjects to merge embedded objects into a new root
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $replaceWith and $replaceRoot?
A$replaceWith emits the original document when the result is null; $replaceRoot errors.
QHow do I merge several fields into a new document?
ACombine with $mergeObjects, e.g. { $replaceWith: { $mergeObjects: ['$a', '$b'] } }.
QDoes $replaceWith keep _id?
ANo, unless the expression explicitly includes _id.
