db.collection.update()

Upsert with Replacement Document

If no document matches the query criteria and the <update> parameter is a replacement document (i.e., contains only field and value pairs), the update inserts a new document with the fields and values of the replacement document.

• If you specify an _id field in either the query parameter or replacement document, MongoDB uses that _id field in the inserted document.

• If you do not specify an _id field in either the query parameter or replacement document, MongoDB generates adds the _id field with a randomly generated ObjectId value.

  You cannot specify different _id field values in the query parameter and replacement document. If you do, the operation errors.

For example, the following update sets the upsert option to true :

db.books.update(
   { item: "ZZZ135" },  // Query parameter
   { $set:
      {
         item: "ZZZ135", stock: 5, tags: [ "database" ]  // Replacement document
      }
   },
   { upsert: true }  // Options
)

WriteResult({
  "nMatched" : 0,
  "nUpserted" : 1,
  "nModified" : 0,
  "_id" : ObjectId("5da78973835b2f1c75347a83")
 })

{
  "_id" : ObjectId("5da78973835b2f1c75347a83"),
  "item" : "ZZZ135",
  "stock" : 5,
  "tags" : [ "database" ]
}

Upsert with Operator Expressions ( $set )

If no document matches the query criteria and the <update> parameter is a document with update operator expressions , then the operation creates a base document from the equality clauses in the <query> parameter and applies the expressions from the <update> parameter.

Comparison operations from the <query> will not be included in the new document. If the new document does not include the _id field, MongoDB adds the _id field with an ObjectId value.

For example, the following update sets the upsert option to true :

db.books.update(
   { item: "BLP921" },   // Query parameter
   {                     // Update document
      $set: { reorder: false },
      $setOnInsert: { stock: 10 }
   },
   { upsert: true }      // Options
)

{
  "_id" : ObjectId("5da79019835b2f1c75348a0a"),
  "item" : "BLP921",
  "reorder" : false,
  "stock" : 10
}

Upsert using an Aggregation Pipeline

If the <update> parameter is an aggregation pipeline , the update creates a base document from the equality clauses in the <query> parameter, and then applies the pipeline to the document to create the document to insert. If the new document does not include the _id field, MongoDB adds the _id field with an ObjectId value.

For example, the following upsert: true operation specifies an aggregation pipeline that uses

• the $replaceRoot stage which can provide somewhat similar behavior to a $setOnInsert update operator expression,

• the $set stage which can provide similar behavior to the $set update operator expression,

• the aggregation variable NOW , which resolves to the current datetime and can provide similar behavior to the $currentDate update operator expression.

db.books.update(
   { item: "MRQ014", ratings: [2, 5, 3] }, // Query parameter
   [                                       // Aggregation pipeline
      { $replaceRoot: { newRoot: { $mergeObjects: [ { stock: 0 }, "$$ROOT"  ] } } },
      { $set: { avgRating: { $avg: "$ratings" }, tags: [ "fiction", "murder" ], lastModified: "$$NOW" } }
   ],
   { upsert: true }   // Options
)

{
   "_id" : ObjectId("5e2921e0b4c550aad59d1ba9"),
   "stock" : 0,
   "item" : "MRQ014",
   "ratings" : [ 2, 5, 3 ],
   "avgRating" : 3.3333333333333335,
   "tags" : [ "fiction", "murder" ],
   "lastModified" : ISODate("2020-01-23T04:32:32.951Z")
}

Using upsert with multi (Match)

From mongosh , insert the following documents into a books collection:

db.books.insertMany( [
  {
    _id: 5,
    item: "RQM909",
    stock: 18,
    info: { publisher: "0000", pages: 170 },
    reorder: true
  },
  {
    _id: 6,
    item: "EFG222",
    stock: 15,
    info: { publisher: "1111", pages: 72 },
    reorder: true
  }
] )

db.books.update(
   { stock: { $gte: 10 } },        // Query parameter
   {                               // Update document
     $set: { reorder: false, tags: [ "literature", "translated" ] }
   },
   { upsert: true, multi: true }   // Options
)

{
   "_id" : 5,
   "item" : "RQM909",
   "stock" : 18,
   "info" : { "publisher" : "0000", "pages" : 170 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}
{
   "_id" : 6,
   "item" : "EFG222",
   "stock" : 15,
   "info" : { "publisher" : "1111", "pages" : 72 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}

Using upsert with multi (No Match)

If the collection had no matching document, the operation would result in the insertion of a single document using the fields from both the <query> and the <update> specifications. For example, consider the following operation:

db.books.update(
  { "info.publisher": "Self-Published" },   // Query parameter
  {                                         // Update document
    $set: { reorder: false, tags: [ "literature", "hardcover" ], stock: 25 }
  },
  { upsert: true, multi: true }             // Options
)

{
  "_id" : ObjectId("5db337934f670d584b6ca8e0"),
  "info" : { "publisher" : "Self-Published" },
  "reorder" : false,
  "stock" : 25,
  "tags" : [ "literature", "hardcover" ]
}

Upsert with Dotted _id Query

When you execute an update() with upsert: true and the query matches no existing document, MongoDB will refuse to insert a new document if the query specifies conditions on the _id field using dot notation .

This restriction ensures that the order of fields embedded in the _id document is well-defined and not bound to the order specified in the query.

If you attempt to insert a document in this way, MongoDB will raise an error. For example, consider the following update operation. Since the update operation specifies upsert:true and the query specifies conditions on the _id field using dot notation, then the update will result in an error when constructing the document to insert.

db.collection.update(
   { "_id.name": "Robert Frost", "_id.uid": 0 },  // Query parameter
   { $set:
      {
         "categories": [ "poet", "playwright" ]  // Replacement document
      }
   },
   { upsert: true }  // Options
)

WriteResult({
  "nMatched" : 0,
  "nUpserted" : 0,
  "nModified" : 0,
  "writeError" : {
    "code" : 111,
    "errmsg" : "field at '_id' must be exactly specified, field at sub-path '_id.name'found"
  }
})