Bulk.find.upsert()¶

On this page

Tip

Starting in version 3.2, MongoDB also provides the db.collection.bulkWrite() method for performing bulk write operations.

Description¶

Bulk.find.upsert()¶

New in version 2.6.

Sets the upsert option to true for an update or a replacement operation and has the following syntax:

Bulk.find(<query>).upsert().update(<update>);
Bulk.find(<query>).upsert().updateOne(<update>);
Bulk.find(<query>).upsert().replaceOne(<replacement>);

With the upsert option set to true, if no matching documents exist for the Bulk.find() condition, then the update or the replacement operation performs an insert. If a matching document does exist, then the update or replacement operation performs the specified update or replacement.

Use Bulk.find.upsert() with the following write operations:

Behavior¶

The following describe the insert behavior of various write operations when used in conjunction with Bulk.find.upsert().

Insert for `Bulk.find.replaceOne()`¶

The Bulk.find.replaceOne() method accepts, as its parameter, a replacement document that only contains field and value pairs:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { item: "abc123" } ).upsert().replaceOne(
   {
     item: "abc123",
     status: "P",
     points: 100,
   }
);
bulk.execute();

If the replacement operation with the Bulk.find.upsert() option performs an insert, the inserted document is the replacement document. If neither the replacement document nor the query document specifies an _id field, MongoDB adds the _id field:

{
  "_id" : ObjectId("52ded3b398ca567f5c97ac9e"),
  "item" : "abc123",
  "status" : "P",
  "points" : 100
}

Insert for `Bulk.find.updateOne()`¶

The Bulk.find.updateOne() method accepts, as its parameter, an update document that contains only field and value pairs or only update operator expressions.

Field and Value Pairs¶

If the update document contains only field and value pairs:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P" } ).upsert().updateOne(
   {
     item: "TBD",
     points: 0,
     inStock: true,
     status: "I"
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the inserted document is the update document. If neither the update document nor the query document specifies an _id field, MongoDB adds the _id field:

{
  "_id" : ObjectId("52ded5a898ca567f5c97ac9f"),
  "item" : "TBD",
  "points" : 0,
  "inStock" : true,
  "status" : "I"
}

Update Operator Expressions¶

If the update document contains contains only update operator expressions:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P", item: null } ).upsert().updateOne(
   {
     $setOnInsert: { defaultQty: 0, inStock: true },
     $currentDate: { lastModified: true },
     $set: { points: "0" }
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the update operation inserts a document with field and values from the query document of the Bulk.find() method and then applies the specified update from the update document. If neither the update document nor the query document specifies an _id field, MongoDB adds the _id field:

{
   "_id" : ObjectId("52ded68c98ca567f5c97aca0"),
   "item" : null,
   "status" : "P",
   "defaultQty" : 0,
   "inStock" : true,
   "lastModified" : ISODate("2014-01-21T20:20:28.786Z"),
   "points" : "0"
}

Insert for `Bulk.find.update()`¶

When using upsert() with the multiple document update method Bulk.find.update(), if no documents match the query condition, the update operation inserts a single document.

The Bulk.find.update() method accepts, as its parameter, an update document that contains only update operator expressions:

var bulk = db.items.initializeUnorderedBulkOp();
bulk.find( { status: "P" } ).upsert().update(
   {
     $setOnInsert: { defaultQty: 0, inStock: true },
     $currentDate: { lastModified: true },
     $set: { status: "I", points: "0" }
   }
);
bulk.execute();

Then, if the update operation with the Bulk.find.upsert() option performs an insert, the update operation inserts a single document with the fields and values from the query document of the Bulk.find() method and then applies the specified update from the update document. If neither the update document nor the query document specifies an _id field, MongoDB adds the _id field:

{
   "_id": ObjectId("52ded81a98ca567f5c97aca1"),
   "status": "I",
   "defaultQty": 0,
   "inStock": true,
   "lastModified": ISODate("2014-01-21T20:27:06.691Z"),
   "points": "0"
}