OPTIONS

db.collection.save()

Definition

db.collection.save()

Updates an existing document or inserts a new document, depending on its document parameter.

The save() method has the following form:

Changed in version 2.6.

db.collection.save(
   <document>,
   {
     writeConcern: <document>
   }
)
Parameter Type Description
document document A document to save to the collection.
writeConcern document

Optional. A document expressing the write concern. Omit to use the default write concern. See Safe Writes.

New in version 2.6.

Changed in version 2.6: The save() returns an object that contains the status of the operation.

Returns:A WriteResult object that contains the status of the operation.

Behavior

Safe Writes

Changed in version 2.6.

The save() method uses either the insert or the update command, which use the default write concern. To specify a different write concern, include the write concern in the options parameter.

Insert

If the document does not contain an _id field, then the save() method calls the insert() method. During the operation, the mongo shell will create an ObjectId and assign it to the _id field.

Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.

Upsert

If the document contains an _id field, then the save() method calls the update() method with the upsert option and a query on the _id field. If a document does not exist with the specified _id value, the save() method, i.e. the update() method with the upsert option, results in an insertion of the document. If a document exists with the specified _id value, the save() method performs an update that replaces all fields in the existing document with the fields from the document.

Examples

Save a New Document without Specifying an _id Field

In the following example, save() method performs an insert since the document passed to the method does not contain the _id field:

db.products.save( { item: "book", qty: 40 } )

During the insert, mongod will create the _id field with a unique ObjectId value, as verified by the inserted document:

{ "_id" : ObjectId("50691737d386d8fadbd6b01d"), "item" : "book", "qty" : 40 }

The ObjectId values are specific to the machine and time when the operation is run. As such, your values may differ from those in the example.

Save a New Document Specifying an _id Field

In the following example, save() performs an update with upsert since the document contains an _id field:

db.products.save( { _id: 100, item: "water", qty: 30 } )

Because the _id field holds a value that does not exist in the collection, the update operation results in an insertion of the document. The results of these operations are identical to an update() method with the upsert flag set to true or 1.

The operation results in the following new document in the products collection:

{ "_id" : 100, "item" : "water", "qty" : 30 }

Replace an Existing Document

The products collection contains the following document:

{ "_id" : 100, "item" : "water", "qty" : 30 }

The save() method performs an update with upsert since the document contains an _id field:

db.products.save( { _id : 100, item : "juice" } )

Because the _id field holds a value that exists in the collection, the operation performs an update to replace the document and results in the following document:

{ "_id" : 100, "item" : "juice" }

Override Default Write Concern

The following operation to a replica set specifies a write concern of "w: majority" with a wtimeout of 5000 milliseconds such that the method returns after the write propagates to a majority of the replica set members or the method times out after 5 seconds.

db.products.save(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

WriteResult

Changed in version 2.6.

The save() returns a WriteResult object that contains the status of the insert or update operation. See WriteResult for insert and WriteResult for update for details.