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

db.collection.update()

Definition

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

Modifies an existing document or documents in a collection. The method can modify specific fields of existing document or documents or replace an existing document entirely, depending on the update parameter.

By default, the update() method updates a single document. If the multi option is set to true, the method updates all documents that match the query criteria.

Changed in version 2.2: Added the following overloaded update() function:

copy

db.collection.update(
   <query>,
   <update>,
   { upsert: <boolean>, multi: <boolean> }
)

Prior to version 2.2, the update() method has the following form:

copy

db.collection.update( <query>, <update>, <upsert>, <multi> )

The update() method takes the following parameters:

Parameter	Type	Description
query	document	The selection criteria for the update. Use the same query selectors as used in the find() method.
update	document	The modifications to apply. For details see Update Parameter.
upsert	boolean	Optional. If set to true, creates a new document when no document matches the query criteria. The default value is false, which does not insert a new document when no match is found. The syntax for this parameter depends on the MongoDB version. See Upsert Parameter.
multi	boolean	Optional. If set to true, updates multiple documents that meet the query criteria. If set to false, updates one document. The default value is false. For additional information, see Multi Parameter.

To update fields in embedded documents, use dot notation.

The update() method can modify the name of a field using the $rename operator.

Update Parameter

The update() method either modifies specific fields in existing documents or replaces an existing document entirely.

Update Specific Fields

If the <update> document contains update operator modifiers, such those using the $set modifier, then:

• The <update> document must contain only update operator expressions.
• The update() method updates only the corresponding fields in the document. For an example, see Update Specific Fields.

Replace a Document Entirely

If the <update> document contains only field:value expressions, and no modifiers, then:

• The update() method replaces the matching document with the <update> document. The update() method does not replace the _id value. For an example, see Replace All Fields.
• update() cannot update multiple documents.

Upsert Parameter

In MongoDB versions 2.2 and later, the upsert parameter has the following form:

copy

upsert : true|false

Prior to version 2.2, the upsert parameter is a positional Boolean. To enable, specify true as the third parameter to update().

Upsert Behavior

If upsert is set to true, and if no document matches the query criteria, update() inserts a single document. The update creates the new document with either:

• The fields and values of the <update> parameter, or
• The fields and values of the both the <query> and <update> parameters. The update creates a document with data from both <query> and <update> if the <update> parameter contains only update operator expressions by taking any equality clauses from the <query> as the base document.

Use Unique Indexes

Warning

To avoid inserting the same document more than once, only use upsert: true if the query field is uniquely indexed.

Given a collection named people where no documents have a name field that holds the value Andy. Consider when multiple clients issue the following update operation at the same time. The following operation becomes an insert because the upsert flag is true.:

copy

db.people.update(
   { name: "Andy" },
   {
      name: "Andy",
      rating: 1,
      score: 1
   },
   { upsert: true }
)

If all update() operations complete the query portion before any client successfully inserts data, and there is no unique index on the name field, then each update operation may perform an insert.

To prevent MongoDB from inserting the same document more than once, create a unique index on the name field. With a unique index, if an applications issues a group of upsert operations, Exactly one update() would successfully insert a new document.

The remaining operations would either:

• update the newly inserted document, or

• fail when they attempted to insert a duplicate.

  If the operation fails because of a duplicate index key error, applications may retry the operation which will succeed as an update operation.

Multi Parameter

In MongoDB versions 2.2 and later, the multi parameter has the following form:

copy

multi : true|false

Prior to version 2.2, the multi parameter is a positional Boolean. To enable the multiple updates, specify true as the fourth parameter to update().

If multi is set to true, the update() method updates all documents that meet the <query> criteria. The multi update operation may interleave with other operations, both read and/or write operations. For unsharded collections, you can override this behavior with the $isolated operator, which isolates the update operation and disallows yielding during the operation. This isolates the update so that no client can see the updated documents until they are all processed, or an error stops the update operation.

If the <update> document contains only field:value expressions, then update() cannot update multiple documents.

For an example, see Update Multiple Documents.

Examples

Update Specific Fields

To update specific fields in a document, use update operators in the <update> parameter. For example, given a books collection with the following document:

copy

{ "_id" : 11, "item" : "Divine Comedy", "stock" : 2 }

The following operation uses the $set and $inc operators to add a price field and to increment stock by 5.

copy

db.books.update(
   { item: "Divine Comedy" },
   {
      $set: { price: 18 },
      $inc: { stock: 5 }
   }
)

The updated document is now the following:

copy

{ "_id" : 11, "item" : "Divine Comedy", "price" : 18, "stock" : 7 }

Update Specific Fields in Embedded Documents

Use dot notation to update values in embedded documents. The following example, which uses the bios collection, queries for the document with _id equal to 1 and updates the value of the field middle in the embedded document named name:

copy

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

Add New Fields

If the <update> parameter contains fields not currently in the document, the update() method adds the new fields to the document. The following operation adds two new fields: mbranch and aka. The operation adds aka in the name document:

copy

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

Remove Fields

The following operation uses the $unset operator to remove the birth field from the document that has _id equal to 3:

copy

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

Replace All Fields

Given the following document in the books collection:

copy

{
    "_id" : 22,
    "item" : "The Banquet",
    "author" : "Dante",
    "price" : 20,
    "stock" : 4
}

The following operation passes an <update> document that contains only field and value pairs, which means the document replaces all the fields in the original document. The operation does not replace the _id value. The operation contains the same value for the item field in both the <query> and <update> documents, which means the field does not change:

copy

db.books.update(
   { item: "The Banquet" },
   { item: "The Banquet", price: 19 , stock: 3 }
)

The operation creates the following new document. The operation removed the author field and changed the values of the price and stock fields:

copy

{
    "_id" : 22,
    "item" : "The Banquet",
    "price" : 19,
    "stock" : 3
}

In the next example, which uses the bios collection, the operation changes all values for the document including the value used to locate the document. The operation locates a document by querying for name set to { first: "John", last: "McCarthy" } and then issues a replacement document that includes the name field set to { first: "Ken", last: "Iverson" }.

copy

db.bios.update(
   { name: { first: "John", last: "McCarthy" } },
   {
      name: { first: "Ken", last: "Iverson" },
      birth: 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"
         }
      ]
   }
)

Insert a New Document if No Match Exists (Upsert)

The following command sets the upsert option to true [1] so that update() creates a new document in the books collection if no document matches the <query> parameter:

copy

db.books.update(
   { item: "The New Life" },
   { item: "The New Life", author: "Dante", price: 15 },
   { upsert: true }
)

If no document matches the <query> parameter, the upsert inserts a document with the fields and values of the <update> parameter and a new unique ObjectId for the _id field:

copy

{
    "_id" : ObjectId("51e5990c95098ed69d4a89f2"),
    "author" : "Dante",
    "item" : "The New Life",
    "price" : 15
}

In the next example, the <update> parameter includes only update operators. If no document matches the <query> parameter, the update operation inserts a document with the fields and values of the both the <query> and <update> parameters:

copy

db.bios.update(
   {
      _id: 7,
      name: { first: "Ken", last: "Thompson" }
   },
   {
      $set: {
         birth: new Date("Feb 04, 1943"),
         contribs: [ "UNIX", "C", "B", "UTF-8" ],
         awards: [
            {
               award: "Turing Award",
               year: 1983,
               by: "ACM"
            },
            {
               award: "IEEE Richard W. Hamming Medal",
               year: 1990,
               by: "IEEE"
            },
            {
               award: "National Medal of Technology",
               year: 1998,
               by: "United States"
            },
            {
               award: "Tsutomu Kanai Award",
               year: 1999,
               by: "IEEE"
            },
            {
               award: "Japan Prize",
               year: 2011,
               by: "The Japan Prize Foundation"
            }
         ]  // end of awards
      } // end of $set
   }, // end of update document
   { upsert: true }
)

[1]	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.

Update Multiple Documents

To update multiple documents, set the multi option to true [2]. The following example queries the bios collection for all documents where awards.award is set to Turing. The update sets the turing field to true:

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.

Combine the Upsert and Multi Parameters

Given a books collection that includes the following documents:

copy

{ _id: 11, author: "Dante", item: "Divine Comedy", price: 18, translatedBy: "abc123" }
{ _id: 12, author: "Dante", item: "Divine Comedy", price: 21, translatedBy: "jkl123" }
{ _id: 13, author: "Dante", item: "Divine Comedy", price: 15, translatedBy: "xyz123" }

The following command specifies the multi parameter to update all documents where item is "Divine Comedy" and the author is "Dante" and specifies the upsert parameter to create a new document if no matching documents are found [3]:

copy

db.books.update(
   { item: "Divine Comedy", author: "Dante" },
   { $set: { reorder: false, price: 10 } },
   { upsert: true, multi: true }
)

The operation updates all three matching documents and results in the following:

copy

{ _id: 11, author: "Dante", item: "Divine Comedy", price: 10, reorder: false, translatedBy: "abc123" }
{ _id: 12, author: "Dante", item: "Divine Comedy", price: 10, reorder: false, translatedBy: "jkl123" }
{ _id: 13, author: "Dante", item: "Divine Comedy", price: 10, reorder: false, translatedBy: "xyz123" }

If the collection had no matching document, the operation would result in the insertion of a document:

copy

{ _id: ObjectId("536aa66422363a21bc16bfd7"), author: "Dante", item: "Divine Comedy", reorder: false, price: 10 }

[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.

Update Arrays

Update an Element by 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 if Position is Unknown

If the position in the array is not known, the update() method can perform the update using the $ positional operator. The array field must appear in the <query> parameter 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

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

The following example queries the bios collection for the first document where the _id field equals 6 and the awards array contains an embedded document where the by field equals ACM. If found, the update() method updates the by field in the first matching embedded document:

copy

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

Add an Element

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" } }
   }
)

In the next example, the $set operator uses dot notation to access the middle field in the name embedded document. The $push operator adds another document to the awards array.

Consider the following operation:

copy

db.bios.update(
   { _id: 1 },
   {
      $set: { "name.middle": "Warner" },
      $push: { awards: {
         award: "IBM Fellow",
            year: "1963",
            by: "IBM"
         }
      }
   }
)

This update() operation:

• Modifies the field name whose value is an embedded document. Specifically, the $set operator updates the middle field in the name document. The document uses dot notation to access a field in an embedded document.
• Adds an element to the field awards, whose value is an array. Specifically, the $push operator adds another document as element to the field awards.

←   db.collection.totalIndexSize() db.collection.validate()  →

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