• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.save()

db.collection.save()

Definition

db.collection.save(document)

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

The save() method takes the following parameter:

Parameter	Type	Description
document	document	A document to save to the collection.

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

If the document contains an _id field, then the save() method performs an upsert, querying the collection on the _id field. If a document does not exist with the specified _id value, the save() method performs an insert. 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

The following are examples of the save() method. The following examples show how to use the save() method to insert or update a document into either the products collection or the bios collection.

Save a New Document without Specifying an _id Field

In the following examples, the parameter to the save() method is a document without an _id field. This means the save() method performs an insert. During the insert, mongod will create the _id field with a unique ObjectId value.

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.

products Collection

This example inserts into the products collection a document with the item field set to book and qty field set to 40:

copy

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

The inserted document includes an _id field with the generated ObjectId value:

copy

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

bios Collection

This example inserts a new document into the The bios Example Collection:

copy

db.bios.save({
   name: { first: 'Guido', last: 'van Rossum'},
   birth: new Date('Jan 31, 1956'),
   contribs: [ 'Python' ],
   awards: [
      {
         award: 'Award for the Advancement of Free Software',
         year: 2001,
         by: 'Free Software Foundation'
      },
      {
         award: 'NLUUG Award',
         year: 2003,
         by: 'NLUUG'
      }
   ]
})

The inserted document includes an _id field with the generated ObjectId value.

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.

Save a New Document Specifying an _id Field

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

products Collection

This example creates a new document with the _id field set to 100, the item field set to water, and the qty field set to 30:

copy

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

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

copy

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

bios Collection

This example creates a new document in the The bios Example Collection. The save() method inserts the document because the bios collection has no document with the _id field equal to 10:

copy

db.bios.save({
   _id: 10,
   name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'},
   birth: new Date('Apr 14, 1965'),
   contribs: [ 'Ruby' ],
   awards: [
      {
         award: 'Award for the Advancement of Free Software',
         year: '2011',
         by: 'Free Software Foundation'
      }
   ]
})

Replace an Existing Document

The following example passes the save() method a document with an _id field. Because the _id field holds a value that does exist in the collection, the operation performs an update to replace the existing document.

products Collection

This example replaces the fields and values of the following document that currently exists in the products collection:

copy

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

To replace the document’s data, pass the save() method a document that contains the _id field set to 100 and the new fields and values:

copy

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

The operation replaces the existing document with the following:

copy

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

←   db.collection.renameCollection() db.collection.stats()  →

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