update( query, update, options )
Modifies an existing document or documents in a collection. The method can modify specific fields of an existing document or documents or replace an existing document entirely, depending on the update parameter.
update()method has the following form:
Changed in version 3.6.
update()method takes the following parameters:
Parameter Type Description
Changed in version 3.0: When you execute an
upsert: trueand the query matches no existing document, MongoDB will refuse to insert a new document if the query specifies conditions on the
_idfield using dot notation.
For more information and an example, see upsert:true with a Dotted _id Query.
document The modifications to apply. For details see Update Parameter.
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.
boolean Optional. If set to
true, updates multiple documents that meet the
querycriteria. If set to
false, updates one document. The default value is
false. For additional information, see Multi Parameter.
New in version 2.6.
Specifies the collation to use for the operation.
Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.
The collation option has the following syntax:
When specifying collation, the
localefield is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.
If the collation is unspecified but the collection has a default collation (see
db.createCollection()), the operation uses the collation specified for the collection.
If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.
You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.
New in version 3.4.
Optional. An array of filter documents that determines which array elements to modify for an update operation on an array field.
In the update document, use the
$[<identifier>]filtered positional operator to define an identifier, which you then reference in the array filter documents. You cannot have an array filter document for an identifier if the identifier is not included in the update document.
<identifier>must begin with a lowercase letter and contain only alphanumeric characters.
You can include the same identifier multiple times in the update document; however, for each distinct identifier (
$[identifier]) in the update document, you must specify exactly one corresponding array filter document. That is, you cannot specify multiple array filter documents for the same identifier. For example, if the update statement includes the identifier
x(possibly multiple times), you cannot specify the following for
arrayFiltersthat includes 2 separate filter documents for
However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:
For examples, see Specify arrayFilters for an Array Update Operations.
New in version 3.6.
Returns: A WriteResult object that contains the status of the operation.
Changed in version 2.6.
update() method uses the
update command, which uses the default write concern. To specify a different write concern, include the
writeConcern option in the options parameter. See Override Default Write Concern for an example.
update() method either modifies specific fields in existing documents or replaces an existing document entirely.
<update>document must contain only update operator expressions.
update()method updates only the corresponding fields in the document.
To update an embedded document or an array as a whole, specify the replacement value for the field. To update particular fields in an embedded document or in an array, use dot notation to specify the field.
<update> document contains only
field:value expressions, then:
true and 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 if the
<update>parameter is a replacement document (i.e., contains only field and value pairs). If neither the
<update>document specifies an
_idfield, MongoDB adds the
_idfield with an ObjectId value.
- The fields and values of both the
<update>parameters if the
<update>parameter contains update operator expressions. The update creates a base document from the equality clauses in the
<query>parameter, and then applies the update expressions from the
<update>parameter. Comparison operations from the
<query>will not be included in the new document.
true and there are documents that match the query criteria,
update() performs an update.
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 with
upsert: true at the same time:
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 result in 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 multiple applications issue the same update with
upsert: true, 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.
When you execute an
upsert: true and the query matches no existing document, MongoDB will refuse to insert a new document if the query specifies conditions on the
_id field using dot notation.
This restriction ensures that the order of fields embedded in the
_id document is well-defined and not bound to the order specified in the query
If you attempt to insert a document in this way, MongoDB will raise an error.
For example, consider the following update operation. Since the update operation specifies
upsert:true and the query specifies conditions on the