MongoDB provides various ways to update a document. The method you use will depend on exactly how you want to perform the update.

This article presents 4 ways to update a document in MongoDB.

The db.collection.updateOne() Method

The db.collection.updateOne() method does exactly as its name promises – it updates one document.

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 could 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.

The db.collection.updateMany() Method

The db.collection.updateMany() method updates all documents that match the specified filter for a collection.

Let’s use the original collection documents:

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

Once again, we can see that two documents have Dog as their type.

We can update both documents at once like this:

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

Result:

{ "acknowledged" : true, "matchedCount" : 2, "modifiedCount" : 2 }

This shows us that two documents matched and two were updated.

We can check the collection:

db.pets.find()

Result:

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

The db.collection.update() Method

The db.collection.update() method can update a single document or multiple 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

Let’s use the original collection of documents again:

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

We could update one 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 go back to the original collection of documents again:

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

And now 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.

The db.collection.replaceOne() Method

The db.collection.replaceOne() method replaces a single document within the collection based on the filter.

Again using the original collection:

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

Let’s see what happens when we use the db.collection.replaceOne() method against it.

db.pets.replaceOne( 
    { type: "Dog" },
    { type: "Cow" }
    )

Result:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

One document was updated.

Let’s take a look.

db.pets.find()

Result:

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

This time, the whole document was replaced with the new document (except for the _id field).

This method replaces the whole document (except for the _id field).

Upsert

All of the above methods accept 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 query criteria, but if there’s no match, a new document is inserted.

Example:

db.pets.updateOne( 
    { name: "Wag" },
    { $set: { type: "Cow" } },
    { upsert: true }
    )

Result:

{
	"acknowledged" : true,
	"matchedCount" : 0,
	"modifiedCount" : 0,
	"upsertedId" : ObjectId("5fe1d5aad991410169410165")
}

In this case, there were no matches, so a document was upserted.

Let’s check the collection.

db.pets.find()

Result:

{ "_id" : 1, "type" : "Cow" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }
{ "_id" : ObjectId("5fe1d5aad991410169410165"), "name" : "Wag", "type" : "Cow" }