Query.prototype.findOneAndUpdate()

Parameters

• [filter] «Object|Query»
• [doc] «Object»

• [options] «Object»

• [options.rawResult] «Boolean» if true, returns the raw result from the MongoDB driver

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

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

• [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.new=false] «Boolean» By default, findOneAndUpdate() 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.

• [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.

• [callback] «Function» optional params are (error, doc), unless rawResult is used, in which case params are (error, writeOpResult)

Returns:

• «Query» this

Issues a mongodb findAndModify update command.

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()

Available options

• new: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
• upsert: bool - creates the object if it doesn’t exist. defaults to false.
• fields: {Object|String} - Field selection. Equivalent to .select(fields).findOneAndUpdate()
• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• maxTimeMS: puts a time limit on the query - requires mongodb >= 2.6.0
• 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.
• rawResult: if true, returns the raw result from the MongoDB driver
• 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.

Callback Signature

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

Examples

query.findOneAndUpdate(conditions, update, options, callback) // executes
query.findOneAndUpdate(conditions, update, options)  // returns Query
query.findOneAndUpdate(conditions, update, callback) // executes
query.findOneAndUpdate(conditions, update)           // returns Query
query.findOneAndUpdate(update, callback)             // returns Query
query.findOneAndUpdate(update)                       // returns Query
query.findOneAndUpdate(callback)                     // executes
query.findOneAndUpdate()                             // returns Query