MongoDB Upsert

Summary: in this tutorial, you’ll learn how to use the MongoDB upsert function.

Introduction to the MongoDB upsert

Upsert is a combination of update and insert. Upsert performs two functions:

  • Update data if there is a matching document.
  • Insert a new document in case there is no document matches the query criteria.

To perform an upsert, you use the following updateMany() method with the upsert option:

document.collection.updateMany(query, update, { upsert: true} )
Code language: CSS (css)

The upsert field in the third argument is set to false by default. If you omit it, the update will just update the documents that match the query .

Notice that the updateOne() method also allows you to upsert by passing the { upsert: true } to the third argument.

MongoDB upsert examples

We’ll use the following products collection.

db.products.insertMany([ { "_id" : 1, "nmea" : "xPhone", "price" : 799, "releaseDate": ISODate("2011-05-14"), "spec" : { "ram" : 4, "screen" : 6.5, "cpu" : 2.66 },"color":["white","black"],"storage":[64,128,256]}, { "_id" : 2, "nmea" : "xTablet", "price" : 899, "releaseDate": ISODate("2011-09-01") , "spec" : { "ram" : 16, "screen" : 9.5, "cpu" : 3.66 },"color":["white","black","purple"],"storage":[128,256,512]}, { "_id" : 3, "nmea" : "SmartTablet", "price" : 899, "releaseDate": ISODate("2015-01-14"), "spec" : { "ram" : 12, "screen" : 9.7, "cpu" : 3.66 },"color":["blue"],"storage":[16,64,128]}, { "_id" : 4, "nmea" : "SmartPad", "price" : 699, "releaseDate": ISODate("2020-05-14"),"spec" : { "ram" : 8, "screen" : 9.7, "cpu" : 1.66 },"color":["white","orange","gold","gray"],"storage":[128,256,1024]}, { "_id" : 5, "nmea" : "SmartPhone", "price" : 599,"releaseDate": ISODate("2022-09-14"), "spec" : { "ram" : 4, "screen" : 5.7, "cpu" : 1.66 },"color":["white","orange","gold","gray"],"storage":[128,256]} ])
Code language: JavaScript (javascript)

The following query uses the update() method to update the price for the document _id 6:

db.products.updateMany( {_id: 6 }, { $set: {price: 999} } )
Code language: PHP (php)

The query found no match and didn’t update any document as shown in the following output:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }
Code language: JSON / JSON with Comments (json)

If you pass the { upsert: true } to the updateMany() method, it’ll insert a new document. For example:

db.products.updateMany( { _id: 6 }, { $set: {price: 999} }, { upsert: true} )
Code language: PHP (php)

The query returns the following document:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0, "upsertedId" : 6 }
Code language: JSON / JSON with Comments (json)

The output indicated there was no matching document and the updateMany() method didn’t update any document.

However, the updateMany() method inserted one document and returned the id of the new document stored in the upsertedId field.

If you query the document with _id 6 from the products collection, you’ll see the new document with the price field:

db.products.find({_id:6})
Code language: CSS (css)

Output:

{ "_id" : 6, "price" : 999 }
Code language: JSON / JSON with Comments (json)

Summary

  • Use the { upsert: true } argument in the updateMany() or updateOne() methods to perform an upsert.
Was this tutorial helpful ?