In MongoDB the db.collection.updateOne()
method updates a single document within the collection based on the filter.
Example
Suppose we have a collection called pets
that contains the following documents:
{ "_id" : 1, "name" : "Wag", "type" : "Dog" } { "_id" : 2, "name" : "Bark", "type" : "Dog" } { "_id" : 3, "name" : "Meow", "type" : "Cat" }
We can update one document like this:
db.pets.updateOne(
{ type: "Dog" },
{ $set: { type: "Cow" } }
)
Result:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
That updated only one document, even though two documents match the filter criteria (the criteria being type: "Dog"
).
We can check the results like this:
db.pets.find()
Result:
{ "_id" : 1, "name" : "Wag", "type" : "Cow" } { "_id" : 2, "name" : "Bark", "type" : "Dog" } { "_id" : 3, "name" : "Meow", "type" : "Cat" }
The first document now has a type
of Cow
instead of Dog
, but the second document was unaffected, even though it also matched the filtering criteria.
Upsert
The db.collection.updateOne()
method accepts an upsert
argument that enables you to perform an upsert operation.
When upsert: true
, the document is updated if there’s a match with the filter criteria, but if there’s no match, a new document is inserted.
Let’s start with the original documents again:
{ "_id" : 1, "name" : "Wag", "type" : "Dog" } { "_id" : 2, "name" : "Bark", "type" : "Dog" } { "_id" : 3, "name" : "Meow", "type" : "Cat" }
Example:
db.pets.updateOne(
{ name: "Bubbles" },
{ $set: { type: "Fish" } },
{ upsert: true }
)
Result:
{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0, "upsertedId" : ObjectId("5fe1e94dd991410169410199") }
In this case, there were no matches, so a document was upserted.
Let’s check the collection.
db.pets.find()
Result:
{ "_id" : 1, "name" : "Wag", "type" : "Dog" } { "_id" : 2, "name" : "Bark", "type" : "Dog" } { "_id" : 3, "name" : "Meow", "type" : "Cat" } { "_id" : ObjectId("5fe1e94dd991410169410199"), "name" : "Bubbles", "type" : "Fish" }
Embedded Documents
You can also use db.collection.updateOne()
to update embedded documents.
Suppose we have the following document:
{ "_id" : 1, "name" : "Wag", "type" : "Dog", "specs" : { "height" : 400, "weight" : 15, "color" : "brown" } }
We can use the following code to update the embedded document.
db.pets.updateOne({
_id: 1
}, {
$set: {
"specs.weight": 20,
"specs.color": "blue"
}
})
Result:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
So we can see that one document was updated.
Let’s check the document.
db.pets.find({
_id: 1
}).pretty()
Result:
{ "_id" : 1, "name" : "Wag", "type" : "Dog", "specs" : { "height" : 400, "weight" : 20, "color" : "blue" } }
We can see that the embedded document was updated as specified.
Arrays
Let’s use db.collection.updateOne()
to update an array.
Suppose we have the following document:
{ "_id" : 1, "name" : "Wag", "type" : "Dog", "awards" : [ "Top Dog", "Best Dog", "Biggest Dog" ] }
Let’s update two of the array elements, and the dog’s name.
db.pets.updateOne({
_id: 1
}, {
$set: {
"name": "Bark",
"awards.0": "Bottom Dog",
"awards.1": "Worst Dog"
}
})
Result:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
We can see that one document was updated.
And let’s look at the document.
db.pets.find().pretty()
Result:
{ "_id" : 1, "name" : "Bark", "type" : "Dog", "awards" : [ "Bottom Dog", "Worst Dog", "Biggest Dog" ] }
The arrayFilters
Parameter
You can also use the arrayFilters
parameter and the positional $
operator to determine which array elements to update.
For example, suppose we have a collection called players
with the following documents:
{ "_id" : 1, "scores" : [ 1, 5, 3 ] } { "_id" : 2, "scores" : [ 8, 17, 18 ] } { "_id" : 3, "scores" : [ 15, 11, 8 ] }
We could run the following query to update only those array elements that have a value higher than a certain amount (in this case 10).
db.players.updateOne(
{ scores: { $gte: 10 } },
{ $set: { "scores.$[e]" : 10 } },
{ arrayFilters: [ { "e": { $gte: 10 } } ] }
)
Result:
{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }
As expected, this only updates one document, even though two documents match the criteria.
Here’s what the documents look like now.
db.players.find()
Result:
{ "_id" : 1, "scores" : [ 1, 5, 3 ] } { "_id" : 2, "scores" : [ 8, 10, 10 ] } { "_id" : 3, "scores" : [ 15, 11, 8 ] }
Document 2 had two array elements updated, because those elements matched the criteria.
More Information
The db.collection.updateOne()
method also accepts other parameters, such as writeConcern
, collation
, and hint
.
See the MongoDB documentation for db.collections.updateOne()
for more information.