Query.prototype.update()

Parameters

• [filter] «Object»

• [doc] «Object» the update command

• [options] «Object»

• [options.multipleCastError] «Boolean» by default, mongoose only returns the first error that occurred in casting the query. Turn on this option to aggregate all the cast errors.

• [options.omitUndefined=false] «Boolean» If true, delete any properties whose value is undefined when casting an update. In other words, if this is set, Mongoose will delete baz from the update in Model.updateOne({}, { foo: 'bar', baz: undefined }) before sending the update to the server.

• [options.strict] «Boolean|String» overwrites the schema’s strict mode option

• [options.upsert=false] «Boolean» if true, and no documents found, insert a new document

• [options.writeConcern=null] «Object» sets the write concern for replica sets. Overrides the schema-level write concern

• [options.timestamps=null] «Boolean» If set to false and schema-level timestamps are enabled, skip timestamps for this update. Does nothing if schema-level timestamps are not set.

• [callback] «Function» params are (error, writeOpResult)

Returns:

• «Query» this

Declare and/or execute this query as an update() operation.

All paths passed that are not atomic operations will become $set ops.

This function triggers the following middleware.

• update()

Example

Model.where({ _id: id }).update({ title: 'words' })
// becomes
Model.where({ _id: id }).update({ $set: { title: 'words' }})

Valid options:

• upsert (boolean) whether to create the doc if it doesn’t match (false)
• multi (boolean) whether multiple documents should be updated (false)
• runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
• setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
• strict (boolean) overrides the strict option for this update
• overwrite (boolean) disables update-only mode, allowing you to overwrite the doc (false)
• context (string) if set to ‘query’ and runValidators is on, this will refer to the query in custom validator functions that update validation runs. Does nothing if runValidators is false.
• read
• writeConcern

Note

Passing an empty object {} as the doc will result in a no-op unless the overwrite option is passed. Without the overwrite option set, the update operation will be ignored and the callback executed without sending the command to MongoDB so as to prevent accidently overwritting documents in the collection.

Note

The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the exec() method.

const q = Model.where({ _id: id });
q.update({ $set: { name: 'bob' }}).update(); // not executed
q.update({ $set: { name: 'bob' }}).exec(); // executed
// keys that are not [atomic](https://docs.mongodb.com/manual/tutorial/model-data-for-atomic-operations/#pattern) ops become `$set`.
// this executes the same command as the previous example.
q.update({ name: 'bob' }).exec();
// overwriting with empty docs
const q = Model.where({ _id: id }).setOptions({ overwrite: true })
q.update({ }, callback); // executes
// multi update with overwrite to empty doc
const q = Model.where({ _id: id });
q.setOptions({ multi: true, overwrite: true })
q.update({ });
q.update(callback); // executed
// multi updates
Model.where()
     .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
// more multi updates
Model.where()
     .setOptions({ multi: true })
     .update({ $set: { arr: [] }}, callback)
// single update by default
Model.where({ email: 'address@example.com' })
     .update({ $inc: { counter: 1 }}, callback)

API summary

update(filter, doc, options, cb) // executes
update(filter, doc, options)
update(filter, doc, cb) // executes
update(filter, doc)
update(doc, cb) // executes
update(doc)
update(cb) // executes
update(true) // executes
update()