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.