Model.findByIdAndUpdate()

Parameters

• id «Object|Number|String» value of _id to query by

• [update] «Object»

• [options] «Object» optional see Query.prototype.setOptions()

• [options.new=false] «Boolean» By default, findByIdAndUpdate() returns the document as it was before update was applied. If you set new: true, findOneAndUpdate() will instead give you the object after update was applied. To change the default to true, use mongoose.set('returnOriginal', false);.

• [options.lean] «Object» if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See Query.lean() and the Mongoose lean tutorial.

• [options.session=null] «ClientSession» The session associated with this query. See transactions docs.

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

• [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.timestamps=null] «Boolean» If set to false and schema-level timestamps are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.

• [options.returnOriginal=null] «Boolean» An alias for the new option. returnOriginal: false is equivalent to new: true.

• [options.overwrite=false] «Boolean» By default, if you don’t include any update operators in update, Mongoose will wrap update in $set for you. This prevents you from accidentally overwriting the document. This option tells Mongoose to skip adding $set. An alternative to this would be using Model.findOneAndReplace({ _id: id }, update, options, callback).

• [callback] «Function»

Returns:

• «Query»

Issues a mongodb findAndModify update command by a document’s _id field. findByIdAndUpdate(id, ...) is equivalent to findOneAndUpdate({ _id: id }, ...).

Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any) to the callback. The query executes if callback is passed.

This function triggers the following middleware.

• findOneAndUpdate()

Options:

• new: bool - true to return the modified document rather than the original. defaults to false
• upsert: bool - creates the object if it doesn’t exist. defaults to 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.
• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• select: sets the document fields to return
• rawResult: if true, returns the raw result from the MongoDB driver
• strict: overwrites the schema’s strict mode option for this update

Examples:

A.findByIdAndUpdate(id, update, options, callback) // executes
A.findByIdAndUpdate(id, update, options)  // returns Query
A.findByIdAndUpdate(id, update, callback) // executes
A.findByIdAndUpdate(id, update)           // returns Query
A.findByIdAndUpdate()                     // returns Query

Note:

All top level update keys which are not atomic operation names are treated as set operations:

Example:

Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options, callback)
// is sent as
Model.findByIdAndUpdate(id, { $set: { name: 'jason bourne' }}, options, callback)

This helps prevent accidentally overwriting your document with { name: 'jason bourne' }.

Note:

Values are cast to their appropriate types when using the findAndModify helpers. However, the below are not executed by default.

• defaults. Use the setDefaultsOnInsert option to override.

findAndModify helpers support limited validation. You can enable these by setting the runValidators options, respectively.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

Model.findById(id, function (err, doc) {
  if (err) ..
  doc.name = 'jason bourne';
  doc.save(callback);
});