MongoDB

Update Methods

MongoDB provides the following methods for updating documents in a collection:

Method	Description
db.collection.updateOne()	Updates at most a single document that match a specified filter even though multiple documents may match the specified filter.  New in version 3.2.
db.collection.updateMany()	Update all documents that match a specified filter.  New in version 3.2.
db.collection.replaceOne()	Replaces at most a single document that match a specified filter even though multiple documents may match the specified filter.   New in version 3.2.
db.collection.update()	Either updates or replaces a single document that match a specified filter or updates all documents that match a specified filter.  By default, the db.collection.update() method updates a single document. To update multiple documents, use the multi option.

These methods accept as parameters:

• a filter document to determine which documents to update. These filters use the same syntax as read operations:
  • A query filter document can specify equality condition with <field>:<value> expressions to select all documents that contain the <field> with the specified <value>:

    { <field1>: <value1>, ... }

  • A query filter document can use the query operators to specify conditions in the following form:

    { <field1>: { <operator1>: <value1> }, ... }

• an update document to specify the modification to perform or a replacement document that wholly replaces the matching documents except for the _id field, and
• an options document.

Behavior

Atomicity

All write operations in MongoDB are atomic on the level of a single document. For more information on MongoDB and atomicity, see Atomicity and Transactions.

_id Field

Once set, you cannot update the value of the _id field nor can you replace an existing document with a replacement document that has a different _id field value.

Document Size

When performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk.

Field Order

MongoDB preserves the order of the document fields following write operations except for the following cases:

• The _id field is always the first field in the document.
• Updates that include renaming of field names may result in the reordering of fields in the document.

Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.

Upsert Option

If db.collection.update(), db.collection.updateOne(), db.collection.updateMany(), or db.collection.replaceOne() includes upsert : true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

For details on the new document created, see the individual reference pages for the methods.

Example Collection

The examples on this page use the db.collection.find() method in the mongo shell. In the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, then the cursor is automatically iterated up to 20 times to print up to the first 20 documents in the results.

To populate the users collection referenced in the examples, run the following in mongo shell:

NOTE: If the users collection already contains documents with the same _id values, you need to drop the collection (db.users.drop()) before inserting the example documents.

db.users.insertMany(
   [
     {
       _id: 1,
       name: "sue",
       age: 19,
       type: 1,
       status: "P",
       favorites: { artist: "Picasso", food: "pizza" },
       finished: [ 17, 3 ],
       badges: [ "blue", "black" ],
       points: [
          { points: 85, bonus: 20 },
          { points: 85, bonus: 10 }
       ]
     },
     {
       _id: 2,
       name: "bob",
       age: 42,
       type: 1,
       status: "A",
       favorites: { artist: "Miro", food: "meringue" },
       finished: [ 11, 25 ],
       badges: [ "green" ],
       points: [
          { points: 85, bonus: 20 },
          { points: 64, bonus: 12 }
       ]
     },
     {
       _id: 3,
       name: "ahn",
       age: 22,
       type: 2,
       status: "A",
       favorites: { artist: "Cassatt", food: "cake" },
       finished: [ 6 ],
       badges: [ "blue", "Picasso" ],
       points: [
          { points: 81, bonus: 8 },
          { points: 55, bonus: 20 }
       ]
     },
     {
       _id: 4,
       name: "xi",
       age: 34,
       type: 2,
       status: "D",
       favorites: { artist: "Chagall", food: "chocolate" },
       finished: [ 5, 11 ],
       badges: [ "Picasso", "black" ],
       points: [
          { points: 53, bonus: 15 },
          { points: 51, bonus: 15 }
       ]
     },
     {
       _id: 5,
       name: "xyz",
       age: 23,
       type: 2,
       status: "D",
       favorites: { artist: "Noguchi", food: "nougat" },
       finished: [ 14, 6 ],
       badges: [ "orange" ],
       points: [
          { points: 71, bonus: 20 }
       ]
     },
     {
       _id: 6,
       name: "abc",
       age: 43,
       type: 1,
       status: "A",
       favorites: { food: "pizza", artist: "Picasso" },
       finished: [ 18, 12 ],
       badges: [ "black", "blue" ],
       points: [
          { points: 78, bonus: 8 },
          { points: 57, bonus: 7 }
       ]
     }
   ]
)

Update Specific Fields in a Document

To change a field in a document, MongoDB provides update operators, such as $set to modify values.

To specify the modification to perform using update operators, use an update document of the form:

{
   <update operator>: { <field1>: <value1>, ... },
   <update operator>: { <field2>: <value2>, ... },
   ...
}

Some update operators, such as $set, will create the field if the field does not exist. See the individual update operator reference.

db.collection.updateOne()

New in version 3.2.

The following example uses the db.collection.updateOne() method on the users collection to update the first document that matches the filter favorites.artist equals "Picasso". The update operation:

• uses the $set operator to update the value of the favorites.food field to "pie" and the value of the type field to 3,
• uses the $currentDate operator to update the value of the lastModified field to the current date. If lastModified field does not exist, $currentDate will create the field. See $currentDate for details.

db.users.updateOne(
   { "favorites.artist": "Picasso" },
   {
     $set: { "favorites.food": "pie", type: 3 },
     $currentDate: { lastModified: true }
   }
)

For more information and examples, see db.collection.updateOne().

db.collection.updateMany()

New in version 3.2.

The following example uses the db.collection.updateMany() method on the users collection to update all documents that matches the filter favorites.artist equals "Picasso". The update operation:

• uses the $set operator to update the value of the favorites.artist field to "Pisanello" and the value of the type field to 3,
• uses the $currentDate operator to update the value of the lastModified field to the current date. If lastModified field does not exist, $currentDate will create the field. See $currentDate for details.

db.users.updateMany(
   { "favorites.artist": "Picasso" },
   {
     $set: { "favorites.artist": "Pisanello", type: 3 },
     $currentDate: { lastModified: true }
   }
)

For more information and examples, see db.collection.updateMany().

db.collection.update

The following example uses the db.collection.update() method on the users collection to update the first document that matches the filter favorites.artist equals "Pisanello". The update operation:

• uses the $set operator to update the value of the favorites.food field to "pizza" and the value of the type field to 0,
• uses the $currentDate operator to update the value of the lastModified field to the current date. If lastModified field does not exist, $currentDate will create the field. See $currentDate for details.

db.users.update(
   { "favorites.artist": "Pisanello" },
   {
     $set: { "favorites.food": "pizza", type: 0,  },
     $currentDate: { lastModified: true }
   }
)

To update multiple documents using the db.collection.update(), include the multi: true option:

db.users.update(
   { "favorites.artist": "Pisanello" },
   {
     $set: { "favorites.food": "pizza", type: 0,  },
     $currentDate: { lastModified: true }
   },
   { multi: true }
)

Replace the Document

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to db.collection.replaceOne() or db.collection.update(). When replacing a document, the replacement document must consist of only <field> : <value>.

The replacement document can have different fields from the original document. In the replacement document, you can omit the _id field since the _id field is immutable; however, if you do include the _idfield, it must have the same value as the current value.

db.collection.replaceOne

The following example uses the db.collection.replaceOne() method on the users collection to replace the first document that matches the filter name equals "abc" with the new document:

db.users.replaceOne(
   { name: "abc" },
   { name: "amy", age: 34, type: 2, status: "P", favorites: { "artist": "Dali", food: "donuts" } }
)

db.collection.update

The following example uses the db.collection.update() method on the users collection to replace the first document that matches the filter name equals "xyz" with the new document:

db.users.update(
   { name: "xyz" },
   { name: "mee", age: 25, type: 1, status: "A", favorites: { "artist": "Matisse", food: "mango" } }
)

Additional Methods

The following methods can also update documents from a collection:

• db.collection.findOneAndReplace().
• db.collection.findOneAndUpdate().
• db.collection.findAndModify().
• db.collection.save().
• db.collection.bulkWrite().

See the individual reference pages for the methods for more information and examples.

Write Acknowledgement

With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see Write Concern.