Docs4dev
Docs
mongodb / v3.6 / reference / reference-method-db.collection.save.html

db.collection.save()

On this page

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 Write Concern.

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

Write Concern

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.

Update

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.

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, the shell 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:true 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 option set to true.

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:true 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 voting replica set members or the method times out after 5 seconds.

Changed in version 3.0: In previous versions, majority referred to the majority of all members of the replica set instead of the majority of the voting members.

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.