MongoDB: db.collection.save() method


The db.collection.save() method is used to updates an existing document or inserts a new document, depending on its document parameter.




Name Description Required /
document A document to save to the collection. Required document
writeConcern A document expressing the write concern. Omit to use the default write concern. Optional document


A WriteResult object that contains the status of the operation.

Example: Save a New Document without Specifying an_idField

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

db.invoice.save( { inv_no: "I00001", inv_date: "10/10/2012", ord_qty:200 } );


> db.invoice.save( { inv_no: "I00001", inv_date: "10/10/2012", ord_qty:200 } );
WriteResult({ "nInserted" : 1 })

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

> db.invoice.find();
{ "_id" : ObjectId("5677ddc7fad7da08e362a3b8"), "inv_no" : "I00001", "inv_date" : "10/10/2012", "ord_qty" : 200 }

Example>: Save a New Document Specifying an_idField

In the following example,save()performs an update withupsert :truesince the document contains an_idfield:

db.invoice.save( { _id: 1001,inv_no: "I00001", inv_date: "10/10/2012", ord_qty:200 } );


> db.invoice.save( { _id: 1001,inv_no: "I00001", inv_date: "10/10/2012", ord_qty:200 } );
WriteResult({ "nMatched" : 0, "nUpserted" : 1, "nModified" : 0, "_id" : 1001 })

The operation results in the following new document in the invoice collection.

> db.invoice.find();
{ "_id" : 1001, "inv_no" : "I00001", "inv_date" : "10/10/2012", "ord_qty" : 200 }

Example: Replace an Existing Document

Theproductscollection contains the following document:

{ "_id" : 1001, "inv_no" : "I00001", "inv_date" : "10/10/2012", "ord_qty" : 200 }

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

db.invoice.save( { _id: 1001,inv_no: "I00015", inv_date: "15/10/2012", ord_qty:500 } );


> db.invoice.save( { _id: 1001,inv_no: "I00015", inv_date: "15/10/2012", ord_qty:500 } );
WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

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:

> db.invoice.find();
{ "_id" : 1001, "inv_no" : "I00015", "inv_date" : "15/10/2012", "ord_qty" : 500 }

Retrieve the restaurants data from here


Safe Writes

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.


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.


If the document contains an _id field, then the save() method is equivalent to an update with the upsert option set to true and the query predicate on the _id field.

Previous: db.collection. renameCollection() method
Next: db.collection.stats() method

Follow us on Facebook and Twitter for latest update.