This version has reached end of life on October 2016. Learn more about upgrading your version of MongoDB.


On this page



New in version 2.4.

If an update operation with upsert: true results in an insert of a document, then $setOnInsert assigns the specified values to the fields in the document. If the update operation does not result in an insert, $setOnInsert does nothing.

You can specify the upsert option for either the db.collection.update() or db.collection.findAndModify() methods.

   { $setOnInsert: { <field1>: <value1>, ... } },
   { upsert: true }

To specify a <field> in an embedded document or in an array, use dot notation.


A collection named products contains no documents.

Then, the following db.collection.update() with upsert: true inserts a new document.

  { _id: 1 },
     $set: { item: "apple" },
     $setOnInsert: { defaultQty: 100 }
  { upsert: true }

MongoDB creates a new document with _id equal to 1 from the <query> condition, and then applies the $set and $setOnInsert operations to this document.

The products collection contains the newly-inserted document:

{ "_id" : 1, "item" : "apple", "defaultQty" : 100 }

If the db.collection.update() with upsert: true had found a matching document, then MongoDB performs an update, applying the $set operation but ignoring the $setOnInsert operation.

←   $rename $set  →