MongoDB Upsert

Have a Database Problem? Speak with an Expert for Free
Get Started >>


The Update operation is one of the CRUD operations that is used to perform modifications in single or multiple records. MongoDB provides the update() method to perform the update operation. The update() method not only updates documents but also provides several options that could be used with it. These options include upsert, multi, writeConcern, collation, and arrayFilter.

The upsert option is very useful. Suppose, we are trying to match a document that we want to update. But the query we have provided does not match any document in the collection. Then, if the upsert option is set to true, then the update() method will insert a new document inside the collation. The content of this document will be the update provided with the method. In this article, we will discuss what is the MongoDB upsert option and how we can use it.

Observe the following collection.

{ "_id" : ObjectId("5e463e67e6f8b824961e87cc"), "name" : "Leonel Messi", "club" : "Barcelona", "country" : "Argentina" }
{ "_id" : ObjectId("5e463ea3e6f8b824961e87cd"), "name" : "Cristiano Ronaldo", "club" : "Juventus", "country" : "Portugal" }
{ "_id" : ObjectId("5e463eb3e6f8b824961e87ce"), "name" : "Neymar", "club" : "PSG", "country" : "Brazil" }
{ "_id" : ObjectId("5e463ecee6f8b824961e87cf"), "name" : "Sergio Ramos", "club" : "Real Madrid", "country" : "Spain" }
{ "_id" : ObjectId("5e463ef9e6f8b824961e87d0"), "name" : "Marc-Andre ter Stegen", "club" : "Barcelona", "country" : "Germany" }

The name of this collection is myteam. It contains data about some of the best footballers in the world. We will use this collection for the demonstration.


To discuss the upsert option, we need a query that does not match any of the documents.

{ "name" : "Sadio Mane"}

This will work fine. There does not exist any document in the myteam collection that can match this query. Now, let’s create the update part.

{ $set : { "club" : "Liverpool" , "country" : "Senegal"}}

Let’s add both of these to the update() method.

db.myteam.update({ "name" : "Sadio Mane"},{ $set : { "club" : "Liverpool" , "country" : "Senegal"}})

Currently, we are not providing the upsert option. Let’s execute it using the mongo shell.

Image from Gyazo

It returns an object. The value of “nMatched” is 0. This means, no document was matched. It won’t because there is no document where the value of the name field is “Sadio Mane”. So if no document was matched, the value of “nModified” should also be 0. It is. But there is something more. The value of “nUpserted” is also 0. So this means, nothing happened here. Now let’s add the upsert option.

db.myteam.update({ "name" : "Sadio Mane"},{ $set : { "club" : "Liverpool" , "country" : "Senegal"}}, {upsert : true})

The upsert option takes a boolean value and it should be the third argument.

Image from Gyazo

This time, the value of “nMatched” and “nModified” is again 0, of course. But the value of “nUpserted” is 1. And we also have the _id field of the new document that was inserted in the collection. Let’s check.

Image from Gyazo

Check the last document.

{ "_id" : ObjectId("5e4ce5378795c8cd70fb295a"), "name" : "Sadio Mane", "club" : "Liverpool", "country" : "Senegal" }

Observe it carefully. The value of the _id field is the same as the value that we had in the returned object. The name field is similar to the query and both club and country fields are similar to the update we provided. This is how the upsert works.


The update() method is an important part of MongoDB. The options that come with it are also very important and useful. Along with upsert, there are various other options too may come handy.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.