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 set to true:

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

The upsert field in the third argument is set to false by default. This means that if you omit it, the method will only update the documents that match the query.

Notice that the updateOne() method also can upsert with the { upsert: true }.

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,
  insertedId: null,
  matchedCount: 0,
  modifiedCount: 0,
  upsertedCount: 0
}
Code language: CSS (css)

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,
  insertedId: 6,
  matchedCount: 0,
  modifiedCount: 0,
  upsertedCount: 1
}
Code language: CSS (css)

The output indicates that there was no matching document (matchedCount is zero) 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: CSS (css)

Summary

• Use the { upsert: true } argument in the updateMany() or updateOne() method to perform an upsert.