Update¶

On this page

Overview
Update
update() Operations with the upsert Flag
Save
Update Operators

Of the four basic database operations (i.e. CRUD), update operations are those that modify existing records or documents in a MongoDB collection. For general information about write operations and the factors that affect their performance, see Write Operations; for documentation of other CRUD operations, see the Core MongoDB Operations (CRUD) page.

Overview¶

Update operation modifies an existing document or documents in a collection. MongoDB provides the following methods to perform update operations:

update
save

Note

Consider the following behaviors of MongoDB’s update operations.

When performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk and may reorder the document fields depending on the type of update.
As of these driver versions, all write operations will issue a getLastError command to confirm the result of the write operation:
copy
```
{ getLastError: 1 }
```
Refer to the documentation on write concern in the Write Operations document for more information.

Update¶

The update() method is the primary method used to modify documents in a MongoDB collection. By default, the update() method updates a single document, but by using the multi option, update() can update all documents that match the query criteria in the collection. The update() method can either replace the existing document with the new document or update specific fields in the existing document.

The update() has the following syntax [1]:

copy

db.collection.update( <query>, <update>, <options> )

Corresponding operation in SQL

The update() method corresponds to the UPDATE operation in SQL, and:

the <query> argument corresponds to the WHERE statement, and
the <update> corresponds to the SET ... statement.

The default behavior of the update() method updates a single document and would correspond to the SQL UPDATE statement with the LIMIT 1. With the multi option, update() method would correspond to the SQL UPDATE statement without the LIMIT clause.

[1]

This examples uses the interface added in MongoDB 2.2 to specify the multi and the upsert options in a document form.

Prior to version 2.2, in the mongo shell, you would specify the upsert and the multi options in the update() method as positional boolean options. See update() for details.

Modify with Update Operators¶

If the <update> argument contains only update operator expressions such as the $set operator expression, the update() method updates the corresponding fields in the document. To update fields in subdocuments, MongoDB uses dot notation.

Update a Field in a Document¶

Use $set to update a value of a field.

The following operation queries the bios collection for the first document that has an _id field equal to 1 and sets the value of the field middle, in the subdocument name, to Warner:

copy

db.bios.update(
   { _id: 1 },
   {
     $set: { 'name.middle': 'Warner' },
   }
)

Add a New Field to a Document¶

If the <update> argument contains fields not currently in the document, the update() method adds the new fields to the document.

The following operation queries the bios collection for the first document that has an _id field equal to 3 and adds to that document a new mbranch field and a new aka field in the subdocument name:

copy

db.bios.update(
   { _id: 3 },
   { $set: {
             mbranch: 'Navy',
             'name.aka': 'Amazing Grace'
           }
   }
)

Remove a Field from a Document¶

If the <update> argument contains $unset operator, the update() method removes the field from the document.

The following operation queries the bios collection for the first document that has an _id field equal to 3 and removes the birth field from the document:

copy

db.bios.update(
   { _id: 3 },
   { $unset: { birth: 1 } }
)

Update Arrays¶

Update an Element by Specifying Its Position¶

If the update operation requires an update of an element in an array field, the update() method can perform the update using the position of the element and dot notation. Arrays in MongoDB are zero-based.

The following operation queries the bios collection for the first document with _id field equal to 1 and updates the second element in the contribs array:

copy

db.bios.update(
   { _id: 1 },
   { $set: { 'contribs.1': 'ALGOL 58' } }
)

Update an Element without Specifying Its Position¶

The update() method can perform the update using the $ positional operator if the position is not known. The array field must appear in the query argument in order to determine which array element to update.

The following operation queries the bios collection for the first document where the _id field equals 3 and the contribs array contains an element equal to compiler. If found, the update() method updates the first matching element in the array to A compiler in the document:

copy

db.bios.update(
       { _id: 3, 'contribs': 'compiler' },
       { $set: { 'contribs.$': 'A compiler' } }
    )

Update a Document Element without Specifying Its Position¶

The update() method can perform the update of an array that contains subdocuments by using the positional operator (i.e. $) and the dot notation.

The following operation queries the bios collection for the first document where the _id field equals 6 and the awards array contains a subdocument element with the by field equal to ACM. If found, the update() method updates the by field in the first matching subdocument:

copy

db.bios.update(
   { _id: 6, 'awards.by': 'ACM'  } ,
   { $set: { 'awards.$.by': 'Association for Computing Machinery' } }
)

Add an Element to an Array¶

The following operation queries the bios collection for the first document that has an _id field equal to 1 and adds a new element to the awards field:

copy

db.bios.update(
   { _id: 1 },
   {
     $push: { awards: { award: 'IBM Fellow', year: 1963, by: 'IBM' } }
   }
)

Update Multiple Documents¶

If the <options> argument contains the multi option set to true or 1, the update() method updates all documents that match the query.

The following operation queries the bios collection for all documents where the awards field contains a subdocument element with the award field equal to Turing and sets the turing field to true in the matching documents [2]:

copy

db.bios.update(
   { 'awards.award': 'Turing' },
   { $set: { turing: true } },
   { multi: true }
)

[2]	Prior to version 2.2, in the `mongo` shell, you would specify the `upsert` and the `multi` options in the `update()` method as positional boolean options. See `update()` for details.

Replace Existing Document with New Document¶

If the <update> argument contains only field and value pairs, the update() method replaces the existing document with the document in the <update> argument, except for the _id field.

The following operation queries the bios collection for the first document that has a name field equal to { first: 'John', last: 'McCarthy' } and replaces all but the _id field in the document with the fields in the <update> argument:

copy

db.bios.update(
   { name: { first: 'John', last: 'McCarthy' } },
   { name: { first: 'Ken', last: 'Iverson' },
     born: new Date('Dec 17, 1941'),
     died: new Date('Oct 19, 2004'),
     contribs: [ 'APL', 'J' ],
     awards: [
               { award: 'Turing Award',
                 year: 1979,
                 by: 'ACM' },
               { award: 'Harry H. Goode Memorial Award',
                 year: 1975,
                 by: 'IEEE Computer Society' },
               { award: 'IBM Fellow',
                 year: 1970,
                 by: 'IBM' }
             ]
   }
)

`update()` Operations with the `upsert` Flag¶

If you set the upsert option in the <options> argument to true or 1 and no existing document match the <query> argument, the update() method can insert a new document into the collection. [3]

The following operation queries the bios collection for a document with the _id field equal to 11 and the name field equal to { first: 'James', last: 'Gosling'}. If the query selects a document, the operation performs an update operation. If a document is not found, update() inserts a new document containing the fields and values from <query> argument with the operations from the <update> argument applied. [4]

copy

db.bios.update(
   { _id:11, name: { first: 'James', last: 'Gosling' } },
   {
     $set: {
             born: new Date('May 19, 1955'),
             contribs: [ 'Java' ],
             awards: [
                       {
                         award: 'The Economist Innovation Award',
                         year: 2002,
                         by: 'The Economist'
                       },
                       {
                         award: 'Officer of the Order of Canada',
                         year: 2007,
                         by: 'Canada'
                       }
                     ]
           }
   },
   { upsert: true }
)

See also Update Operations with the Upsert Flag in the Create document.

[3]	Prior to version 2.2, in the `mongo` shell, you would specify the `upsert` and the `multi` options in the `update()` method as positional boolean options. See `update()` for details.

[4] If the <update> argument includes only field and value pairs, the new document contains the fields and values specified in the <update> argument. If the <update> argument includes only update operators, the new document contains the fields and values from <query> argument with the operations from the <update> argument applied.

Save¶

The save() method performs a special type of update(), depending on the _id field of the specified document.

The save() method has the following syntax:

copy

db.collection.save( <document> )

Behavior¶

If you specify a document with an _id field, save() performs an update() with the upsert option set: if an existing document in the collection has the same _id, save() updates that document, and inserts the document otherwise. If you do not specify a document with an _id field to save(), performs an insert() operation.

That is, save() method is equivalent to the update() method with the upsert option and a <query> argument with an _id field.

Example

Consider the following psudocode explanation of save() as an illustration of its behavior:

copy

function save( doc ) {
  if( doc["_id"] ) {
       update( {_id: doc["_id"] }, doc, { upsert: true } );
    }
  else {
       insert(doc);
  }
}

Save Performs an Update¶

If the <document> argument contains the _id field that exists in the collection, the save() method performs an update that replaces the existing document with the <document> argument.

The following operation queries the bios collection for a document where the _id equals ObjectId("507c4e138fada716c89d0014") and replaces the document with the <document> argument:

copy

db.bios.save(
   {
     _id: ObjectId("507c4e138fada716c89d0014"),
     name: { first: 'Martin', last: 'Odersky' },
     contribs: [ 'Scala' ]
   }
)

Update¶

Overview¶

Update¶

Modify with Update Operators¶

Update a Field in a Document¶

Add a New Field to a Document¶

Remove a Field from a Document¶

Update Arrays¶

Update an Element by Specifying Its Position¶

Update an Element without Specifying Its Position¶

Update a Document Element without Specifying Its Position¶

Add an Element to an Array¶

Update Multiple Documents¶

Replace Existing Document with New Document¶

`update()` Operations with the `upsert` Flag¶

Save¶

Behavior¶

Save Performs an Update¶

Update Operators¶

Fields¶

Array¶

Bitwise¶

Isolation¶

Update¶

Overview¶

Update¶

Modify with Update Operators¶

Update a Field in a Document¶

Add a New Field to a Document¶

Remove a Field from a Document¶

Update Arrays¶

Update an Element by Specifying Its Position¶

Update an Element without Specifying Its Position¶

Update a Document Element without Specifying Its Position¶

Add an Element to an Array¶

Update Multiple Documents¶

Replace Existing Document with New Document¶

update() Operations with the upsert Flag¶

Save¶

Behavior¶

Save Performs an Update¶

Update Operators¶

Fields¶

Array¶

Bitwise¶

Isolation¶

`update()` Operations with the `upsert` Flag¶