updateOne() (Update Single)
Last updated: 2026-10-09
updateOne() (Update Single)
updateOne() updates the first document matching a filter. If multiple match, only the first (in natural order) is updated. Modifications are expressed with update operators ($set/$inc/$push...). The result includes matchedCount, modifiedCount, and upsertedId.
| Category | Write |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
db.<collection>.updateOne(<filter>, <update>, { upsert: <bool> })⚙️ Parameters
| filter | Predicate object matching documents; supports query operators. |
|---|---|
| update | Object of update operators, e.g. {$set: {age: 22}}. |
| upsert | Optional. Insert a new document when nothing matches; default false. |
Returns：UpdateResult: { acknowledged, matchedCount, modifiedCount, upsertedId }.
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// updateOne: set Alice's age to 22
db.users.updateOne(
{ name: "Alice" },
{ $set: { age: 22 } }
)Output：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 Notes
- Updates only the first match; use updateMany() for all
- The update document must use update operators — use replaceOne() to overwrite wholesale
- With upsert: true, inserts a new document when nothing matches
- Conflicting operators on the same field (e.g. $set and $inc) are disallowed
🏷️ Related Tags
💡 Related Cases
📚 Related Tutorials
❓ FAQ
QWhat is the difference between updateOne and findOneAndUpdate?
AupdateOne returns only counters (matched/modifiedCount); findOneAndUpdate returns the pre- (or post-) update document, handy when you need the old/new value.
QWhat happens if updateOne matches multiple documents?
AIt updates only the first matched document. Use updateMany to update all matches; if the ordering matters, pass the sort option to control which document is treated as first.
QCan updateOne combine $set and $inc?
AYes. The update document can hold multiple operators, e.g. { $set: { status: 'active' }, $inc: { visits: 1 } }, applied atomically in order.
