In MongoDB the db.collection.update() method modifies an existing document or documents in a collection.

By default, it only updates a single document. But if multi: true is specified, then it updates all documents that match the query criteria.

Update a Single Document

Suppose we have the collection called pets with the following documents:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

We can update a single document like this:

db.pets.update( 
    { type: "Dog" },
    { $set: { type: "Cow" } }
    )

Result:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

Only one document was updated. This is confirmed when we query the collection.

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Cow" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

Update Multiple Documents

Let’s use the original documents again:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

This time we’ll add multi: true to our update operation to update all documents that match the query criteria:

db.pets.update( 
    { type: "Dog" },
    { $set: { type: "Cow" } },
    { multi: true }
    )

Result:

WriteResult({ "nMatched" : 2, "nUpserted" : 0, "nModified" : 2 }) 

So two documents were matched and updated this time.

Let’s look at our collection again:

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Cow" }
{ "_id" : 2, "name" : "Bark", "type" : "Cow" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

As expected, both documents now have a type of Cow.

Upsert

The db.collection.update() 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.update( 
    { name: "Bubbles" },
    { $set: { type: "Fish" } },
    { upsert: true }
    )

Result:

 WriteResult({
 "nMatched" : 0,
 "nUpserted" : 1,
 "nModified" : 0,
 "_id" : ObjectId("5fe2c925d9914101694102e1")
 }) 

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("5fe2c925d9914101694102e1"), "name" : "Bubbles", "type" : "Fish" } 

Embedded Documents

You can also use db.collection.update() 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.update({ 
    _id: 1 
    }, { 
        $set: { 
            "specs.weight": 20, 
            "specs.color": "blue"
        } 
})

Result:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) 

So we can see that one document was matched and modified.

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.update() 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.update({ 
    _id: 1 
    }, { 
        $set: { 
            "name": "Bark",
            "awards.0": "Bottom Dog", 
            "awards.1": "Worst Dog"
        } 
})

Result:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) 

We can see that one document was matched and modified.

And now 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.update(
   { scores: { $gte: 10 } },
   { $set: { "scores.$[e]" : 10 } },
   { arrayFilters: [ { "e": { $gte: 10 } } ] }
)

Result:

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) 

As expected, this only updates one document, even though two documents match the criteria (because we didn’t specify multi: true).

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.update() method also accepts other parameters, such as writeConcern, collation, and hint.

See the MongoDB documentation for db.collections.update() for more information.