- Reference >
- JavaScript Methods >
- db.collection.update()
db.collection.update()¶
-
db.collection.
update
(query, update[, options])¶ The
update()
method modifies an existing document or documents in a collection. By default theupdate()
method updates a single document. To update all documents in the collection that match the update query criteria, specify themulti
option. To insert a document if no document matches the update query criteria, specify theupsert
option.Changed in version 2.2: The
mongo
shell provides an updated interface that accepts the options parameter in a document format to specifymulti
andupsert
options.Prior to version 2.2, in the
mongo
shell,upsert
andmulti
were positional boolean options: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 thedb.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 onlyupdate operators
expressions. - the
update()
method updates only the corresponding fields in the document.
If the
update
parameter consists only offield: value
expressions, then: - the
- 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 individualupsert
andmulti
parameters. - upsert (boolean) –
Optional. Specifies an upsert operation
The default value is
false
. Whentrue
, theupdate()
method will update an existing document that matches thequery
selection criteria or if no document matches the criteria, insert a new document with the fields and values of theupdate
parameter and if theupdate
included onlyupdate operators
, thequery
parameter as well .In version 2.2 of the
mongo
shell, you may also specifyupsert
in theoptions
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 theupdate()
method updates a single document that meet thequery
criteria.When
true
, theupdate()
method updates all documents that meet thequery
criteria.In version 2.2 of the
mongo
shell, you may also specifymulti
in theoptions
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 thefield
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 anupdate
parameter usingfield: value
pairs and expressions using update operators as in the following:This operation updates a document in the
products
collection that matches the query criteria and sets the value of the fieldx
to6
, and increment the value of the fieldy
by5
. 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 theupdate()
method with anupdate
parameter that consists of onlykey: value
expressions, as in the following:This operation selects a document from the
products
collection that matches the query criteria sets the value of the fieldx
to6
and the value of the fieldy
to15
. All other fields of the matched document are removed, except the _id field.To update multiple documents, call the
update()
method and specify themulti
option in theoptions
argument, as in the following:This operation updates all documents in the
products
collection that match the query criteria by setting the value of the fieldx
to6
and the value of the fieldy
to15
. This operation does not affect any other fields in documents in theproducts
collection.You can perform the same operation by calling the
update()
method with themulti
parameter:To update a document or to insert a new document if no document matches the query criteria, call the
update()
and specify theupsert
option in theoptions
argument, as in the following:This operation will:
- update a single document in the
products
collection that matches the query criteria, setting the value of the fieldx
to25
and the value of the fieldy
to50
, or - if no matching document exists, insert a document in the
products
collection, with the fielditem
set tomagazine
, the fieldx
set to25
, and the fieldy
set to50
.
- update a single document in the
- query (document) – Specifies the selection criteria for the
update. The