When would you use findOneAndUpdate instead of updateOne in MongoDB?

## Two APIs, one difference that matters Both `updateOne` and `findOneAndUpdate` modify a single document that a filter selects. The difference is what comes back and how the target is chosen. `updateOne(filter, update, options)` returns a small result object: `matchedCount`, `modifiedCount`, and — for an upsert — `upsertedId`. If the application needs the document's contents afterwards, it must issue a separate `find`, and between the write and that read another client may have changed the document again. The value you read back is then not necessarily the value your write produced. `findOneAndUpdate(filter, update, options)` returns the document itself. The select-and-modify is a single server-side operation on one document, so the document you are handed is exactly the one your update touched. ## returnDocument By default `findOneAndUpdate` returns the document **as it was before** the update. Passing `returnDocument: "after"` returns the post-update state instead. (The legacy mongo shell spelled this `returnNewDocument: true`; current drivers and mongosh use `returnDocument` with `"before"` or `"after"`.) Which you want depends on the use case: an audit trail usually wants the previous values, while a counter or a claimed job wants the new ones. If no document matches and `upsert` is not requested, the command returns null rather than raising an error. ## The sort option This is the capability people forget. `updateOne` gives no control over which of several matching documents is modified. `findOneAndUpdate` accepts `sort`, so you can say "of all pending jobs, take the highest priority, oldest first": ```js const job = db.jobs.findOneAndUpdate( { status: "pending" }, { $set: { status: "running", startedAt: new Date() } }, { sort: { priority: -1, createdAt: 1 }, returnDocument: "after" } ) ``` Because the find and the modify happen as one operation on that document, two workers running this concurrently cannot both receive the same job: whichever executes second no longer sees it as `pending`. This is the canonical job-claim pattern, and it is why the operation exists. As with any query that sorts, the sort should be supported by an index or it will be doing work in memory on every claim. ## Getting a computed value back The second classic use is a value the server computes: ```js const c = db.counters.findOneAndUpdate( { _id: "invoice" }, { $inc: { seq: 1 } }, { returnDocument: "after", upsert: true } ) // c.seq is the number this caller owns ``` Each caller receives a distinct number. Doing the same with `updateOne` followed by `find` would let a concurrent increment slip in between, so two callers could read the same value. ## Other options `projection` limits the fields of the returned document — useful when the document is large but you only need a field or two. `upsert: true` behaves as it does elsewhere, and combined with `returnDocument: "after"` it gives you the created document. `arrayFilters` works exactly as it does for `updateOne`, so filtered positional updates are available. There are sibling commands with the same shape: `findOneAndReplace` and `findOneAndDelete`, the latter being how you claim-and-remove from a queue collection. ## Costs and limits `findOneAndUpdate` touches exactly one document — there is no "findManyAndUpdate". Returning the document means shipping it back to the client, which for a large document is real bandwidth you did not spend with `updateOne`; a `projection` trims that. And because a claim pattern concentrates many clients on the same small set of documents, contention on the hottest documents is the thing to watch as worker count grows: every claimer is competing to modify the head of the same queue. ## Choosing between them Default to `updateOne` — it is cheaper and says exactly what it does. Reach for `findOneAndUpdate` when the response must carry the document, when a sort must pick the target, or when the read-back must be free of interference from concurrent writers. Reach for `updateMany` when the change applies to a set of documents; `findOneAndUpdate` is not the tool for bulk changes.