deno.land / x / mongoose@6.7.5 / docs / tutorials / findoneandupdate.md
findOneAndUpdate()
in MongooseThe findOneAndUpdate()
function in Mongoose has a wide variety of use cases. You should use save()
to update documents where possible, but there are some cases where you need to use findOneAndUpdate()
. In this tutorial, you'll see how to use findOneAndUpdate()
, and learn when you need to use it.
As the name implies, findOneAndUpdate()
finds the first document that matches a given filter
, applies an update
, and returns the document. By default, findOneAndUpdate()
returns the document as it was before update
was applied.
[require:Tutorial.*findOneAndUpdate.*basic case]
You should set the new
option to true
to return the document after update
was applied.
[require:Tutorial.*findOneAndUpdate.*new option]
Mongoose's findOneAndUpdate()
is slightly different from the MongoDB Node.js driver's findOneAndUpdate()
because it returns the document itself, not a result object.
As an alternative to the new
option, you can also use the returnOriginal
option.
returnOriginal: false
is equivalent to new: true
. The returnOriginal
option
exists for consistency with the the MongoDB Node.js driver's findOneAndUpdate()
,
which has the same option.
[require:Tutorial.*findOneAndUpdate.*returnOriginal option]
With the exception of an unindexed upsert, findOneAndUpdate()
is atomic. That means you can assume the document doesn't change between when MongoDB finds the document and when it updates the document, unless you're doing an upsert.
For example, if you're using save()
to update a document, the document can change in MongoDB in between when you load the document using findOne()
and when you save the document using save()
as show below. For many use cases, the save()
race condition is a non-issue. But you can work around it with findOneAndUpdate()
(or transactions) if you need to.
[require:Tutorial.*findOneAndUpdate.*save race condition]
Using the upsert
option, you can use findOneAndUpdate()
as a find-and-upsert operation. An upsert behaves like a normal findOneAndUpdate()
if it finds a document that matches filter
. But, if no document matches filter
, MongoDB will insert one by combining filter
and update
as shown below.
[require:Tutorial.*findOneAndUpdate.*upsert]
Mongoose transforms the result of findOneAndUpdate()
by default: it
returns the updated document. That makes it difficult to check whether
a document was upserted or not. In order to get the updated document
and check whether MongoDB upserted a new document in the same operation,
you can set the rawResult
flag to make Mongoose return the raw result
from MongoDB.
[require:Tutorial.*findOneAndUpdate.*rawResult$]
Here's what the res
object from the above example looks like:
{ lastErrorObject:
{ n: 1,
updatedExisting: false,
upserted: 5e6a9e5ec6e44398ae2ac16a },
value:
{ _id: 5e6a9e5ec6e44398ae2ac16a,
name: 'Will Riker',
__v: 0,
age: 29 },
ok: 1 }
Version Info