db.collection.update()¶

db.collection.update(query, update[, options])¶

The update() method modifies an existing document or documents in a collection. By default the update() method updates a single document. To update all documents in the collection that match the update query criteria, specify the multi option. To insert a document if no document matches the update query criteria, specify the upsert option.

Changed in version 2.2: The mongo shell provides an updated interface that accepts the options parameter in a document format to specify multi and upsert options.

Prior to version 2.2, in the mongo shell, upsert and multi were positional boolean options:

copy

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

The update() method takes the following parameters:

Parameters:

query (document) – Specifies the selection criteria for the update. The query parameter employs the same query selectors as used in the db.collection.find() method.
update (document) –
Specifies the modifications to apply.

If the update parameter contains any update operators expressions such as the $set operator expression, then:
- the update parameter must contain only update operators expressions.
- the update() method updates only the corresponding fields in the document.
If the update parameter consists only of field: value expressions, then:
- the update() method replaces the document with the updates document. If the updates document is missing the _id field, MongoDB will add the _id field and assign to it a unique objectid .
- the update() method updates cannot update multiple documents.
options (document) –

New in version 2.2.

Optional. Specifies whether to perform an upsert and/or a multiple update. Use the options parameter instead of the individual upsert and multi parameters.
upsert (boolean) –
Optional. Specifies an upsert operation

The default value is false. When true, the update() method will update an existing document that matches the query selection criteria or if no document matches the criteria, insert a new document with the fields and values of the update parameter and if the update included only update operators, the query parameter as well .

In version 2.2 of the mongo shell, you may also specify upsert in the options parameter.

Note

With upsert update() inserts a single document.
multi (boolean) –
Optional. Specifies whether to update multiple documents that meet the query criteria.

When not specified, the default value is false and the update() method updates a single document that meet the query criteria.

When true, the update() method updates all documents that meet the query criteria.

In version 2.2 of the mongo shell, you may also specify multi in the options parameter.

Note

The multi update operation may interleave with other 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. See $isolated.

Although the update operation may apply mostly to updating the values of the fields, the update() method can also modify the name of the field in a document using the $rename operator.

Consider the following examples of the update() method. These examples all use the 2.2 interface to specify options in the document form.

To update specific fields in a document, call the update() method with an update parameter using field: value pairs and expressions using update operators as in the following:
copy
```
db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } )
```
This operation updates a document in the products collection that matches the query criteria and sets the value of the field x to 6, and increment the value of the field y by 5. All other fields of the document remain the same.
To replace all the fields in a document with the document as specified in the update parameter, call the update() method with an update parameter that consists of only key: value expressions, as in the following:
copy
```
db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } )
```
This operation selects a document from the products collection that matches the query criteria sets the value of the field x to 6 and the value of the field y to 15. All other fields of the matched document are removed, except the _id field.
To update multiple documents, call the update() method and specify the multi option in the options argument, as in the following:
copy
```
db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } )
```
This operation updates all documents in the products collection that match the query criteria by setting the value of the field x to 6 and the value of the field y to 15. This operation does not affect any other fields in documents in the products collection.

You can perform the same operation by calling the update() method with the multi parameter:
copy
```
db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, false, true )
```
To update a document or to insert a new document if no document matches the query criteria, call the update() and specify the upsert option in the options argument, as in the following:
copy
```
db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 25, y: 50 } }, { upsert: true } )
```
This operation will:
- update a single document in the products collection that matches the query criteria, setting the value of the field x to 25 and the value of the field y to 50, or
- if no matching document exists, insert a document in the products collection, with the field item set to magazine, the field x set to 25, and the field y set to 50.

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