In MongoDB, what is the difference between updateOne with $set and replaceOne?

## The two write shapes MongoDB gives you two ways to change an existing document, and interviewers ask about the difference because choosing the wrong one silently destroys data. `db.collection.updateOne(filter, update, options)` performs a **targeted modification**. The `update` argument is not a document you want stored — it is a set of instructions, each keyed by an update operator: `$set`, `$unset`, `$inc`, `$mul`, `$min`, `$max`, `$rename`, `$currentDate`, plus the array operators `$push`, `$addToSet`, `$pull` and `$pop`. The server applies those instructions to the matched document and leaves every field the instructions do not mention exactly as it was. `db.collection.replaceOne(filter, replacement, options)` performs a **whole-document substitution**. The `replacement` argument is a normal document with no operators, and after the write the stored document *is* that document (plus its `_id`). Every field you did not include is gone. ## Update operators are mandatory for updateOne A very common beginner mistake is calling `db.users.updateOne({ _id: 1 }, { name: "Ada" })`. That is rejected: the update document must contain atomic operators. The correct form is `{ $set: { name: "Ada" } }`. Older MongoDB shells did allow a `db.collection.update()` call with a bare document, and it behaved as a *replacement* — which is exactly the trap. The modern CRUD API makes the two intentions explicit, which is why the legacy `update()`/`remove()` helpers were dropped from current drivers in favour of `updateOne`/`updateMany`/`replaceOne`/`deleteOne`/`deleteMany`. ## What $set actually does `$set` sets a field to a value, creating the field if it is absent. With dot notation it reaches inside embedded documents and arrays: `{ $set: { "address.city": "Berlin" } }` rewrites just that one field and, if `address` does not exist, creates it as an embedded document. `{ $set: { "items.0.qty": 3 } }` targets a specific array index. Its mirror image is `$unset`, which removes a field entirely — the value you give `$unset` is ignored, so `{ $unset: { nickname: "" } }` is idiomatic. One detail worth knowing: if a document already has the exact value you are setting, the write matches but does not modify. The result object distinguishes `matchedCount` from `modifiedCount`, and a `modifiedCount` of 0 with `matchedCount` of 1 means "found it, nothing changed" — not a failure. ## _id is immutable Neither operation may change `_id`. A `$set` on `_id` is an error, and a `replaceOne` whose replacement carries a different `_id` is an error too. Omitting `_id` from the replacement is fine — the existing one is kept. ## Why replaceOne is the riskier choice `replaceOne` is usually the tail end of a read-modify-write cycle: the application loads a document, mutates an object in memory, and writes the whole thing back. That pattern has two problems. First, it is **lossy across schema change**: if another version of the service (or a background job) added a field the reader's model does not know about, serializing the model back over the document deletes that field. Second, it is **lossy under concurrency**: between the read and the write, another client may have changed a different field of the same document, and the replacement overwrites their change with the stale value the reader loaded. Field-level operators avoid both, because two clients touching different fields of the same document do not overwrite each other, and a counter changed with `$inc` never depends on the value the client last read. The practical rule: use `$set` and friends by default, and reach for `replaceOne` only when you genuinely mean "this document should now be exactly this" — for example when re-materializing a document from an authoritative source. ## Multi-document and bulk variants `updateMany` applies the same operator document to every match; there is deliberately no `replaceMany`, because replacing many documents with one identical body is almost never intended. Both `updateOne` and `replaceOne` accept `{ upsert: true }`, and both are available as operations inside `bulkWrite`. ## Updates written as an aggregation pipeline Since MongoDB 4.2, the update argument may also be an aggregation pipeline — an array such as `[ { $set: { total: { $add: ["$price", "$tax"] } } } ]`. That form lets a field be computed from other fields of the same document in one server-side write, which plain update operators cannot do. It is still an update, not a replacement: stages you do not write leave the rest of the document alone.