Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
mongo Shell Methods
/
Collection Methods

db.collection.save()

On this page

  • Definition
  • Behavior
  • Examples
  • WriteResult

Definition

db.collection.save()

Important

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.

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

Note

Starting in MongoDB 4.2, the db.collection.save() method is deprecated. Use db.collection.insertOne() or db.collection.replaceOne() instead.

The save() method has the following form:

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.

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

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

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.

Transactions

db.collection.save() can be used inside distributed transactions.

For feature compatibility version (fcv) "4.4" and greater, if you save a document to a non-existing collection in a transaction, the collection is implicitly created.

Note

You cannot create new collections in cross-shard write transactions. For example, if you write to an existing collection in one shard and implicitly create a collection in a different shard, MongoDB cannot perform both operations in the same transaction.

For fcv "4.2" or less, save() operations that would result in the creation of a new collection are not allowed in a transaction.

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Important

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.

Sharded Clusters

Starting in MongoDB 4.2, the save() method cannot be used with sharded collections that are not sharded by _id, and attempting to do so will result in an error. Use the insertOne() or replaceOne() method instead.

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.

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

WriteResult

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.

Back

db.collection.replaceOne()

Next

db.collection.stats()