Navigation
This version of the documentation is archived and no longer supported.

Bulk.find.upsert()

On this page

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:

copy 
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:

copy 
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 the replacement document does not specify an _id field, MongoDB adds the _id field:

copy 
{
  "_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:

copy 
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 the update document does not specify an _id field, MongoDB adds the _id field:

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

Update Operator Expressions

If the <update> document contains contains only update operator expressions:

copy 
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:

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

If neither the <query> document nor the <update> document specifies an _id field, MongoDB adds the _id field.

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:

copy 
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:

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

If neither the <query> document nor the <update> document specifies an _id field, MongoDB adds the _id field.

See also

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.