- Stitch >
- MongoDB Atlas >
- Reference >
- MongoDB Actions
collection.findOneAndReplace()¶
On this page
Definition¶
-
collection.
findOneAndReplace
()¶
Overwrite a single document in a collection or view based on a query filter and return the document in either
its pre-replacement or post-replacement form. Unlike
collection.updateOne()
, this action allows you to atomically
find, replace, and return a document with the same command. This avoids
the risk of other update operations changing the document between
separate find and update operations.
Usage¶
Example¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
To call the collection.findOneAndUpdate()
action from a
Function, get a collection handle with
database.collection()
then call the handle’s
findOneAndUpdate()
method.
To call the collection.findOneAndReplace()
action from a
JavaScript SDK, use the
RemoteMongoCollection.findOneAndReplace() method.
To call the collection.findOneAndReplace()
action from the
Java/Android SDK, use the
RemoteMongoCollection.findOneAndReplace() method.
Parameters¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
The collection.findOneAndReplace()
action has the following
form:
Parameter | Description |
---|---|
Query Filter query: <document> |
Required. A standard MongoDB query document that specifies which document to replace. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. If multiple documents match the query, only the first document in sort order or natural order will be updated. |
Replacement Document replacement: <document> |
Required. The document that should replace the found document. The document cannot contain any MongoDB update operators. |
Replacement Options options: <document> |
A document that specifies configuration options for the query.
The |
Upsert options.upsert: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that MongoDB should insert a new document that
matches the query filter when the query does not match any
existing documents in the collection. |
Sort options.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
Projection options.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query. To return all fields in the matching documents, omit this
parameter or specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
Return New Document options.returnNewDocument: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that the action should return the document in its
post-replace form instead of its original form from before the
replace operation. |
The findOneAndReplace() method has the following form:
Parameter | Description |
---|---|
Query Filter query: <document> |
Required. A standard MongoDB query document that specifies which document to replace. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. If multiple documents match the query, only the first document in sort order or natural order will be updated. |
Replacement Document replacement: <document> |
Required. The document that should replace the found document. The document cannot contain any MongoDB update operators. |
Replacement Options options: <document> |
A document that specifies configuration options for the query.
The |
Upsert options.upsert: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that MongoDB should insert a new document that
matches the query filter when the query does not match any
existing documents in the collection. |
Sort options.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
Projection options.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query. To return all fields in the matching documents, omit this
parameter or specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
Return New Document options.returnNewDocument: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that the action should return the document in its
post-replace form instead of its original form from before the
replace operation. |
The findOneAndReplace() method has the following form:
Parameter | Description |
---|---|
Query Filter filter: <document> |
Required. A standard MongoDB query document that specifies which document to replace. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. If multiple documents match the query, only the first document in sort order or natural order will be replaced. |
Replacement Document replacement: <document> |
Required. The document that should replace the found document. The document cannot contain any MongoDB update operators. |
Update Options options: <RemoteFindOneAndModifyOptions> |
Optional: An instance of the RemoteFindOneAndModifyOptions. class. |
Sort RemoteFindOneAndModifyOptions.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
Projection RemoteFindOneAndModifyOptions.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in the document returned by the query. To return all fields in the matching document, omit this
parameter or specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
Upsert RemoteFindAndModifyOptions.upsert: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that MongoDB should insert a new document that
matches the query filter when the query does not match any
existing documents in the collection. |
Return New Document RemoteFindAndModifyOptions.returnNewDocument: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that the action should return the document in its
post-replace form instead of its original form from before the
replace operation. |
Result Class resultClass: <class> |
Optional. Indicates the type of the document returned by the operation. |
Parameter | Description |
---|---|
Query Filter filter: <document> |
Required. A standard MongoDB query document that specifies which document to update. You can use most query selectors except for evaluation, geospatial, or bitwise selectors. If multiple documents match the query, only the first document in sort order or natural order will be updated. |
Replacement Document replacement: <document> |
Required. The document that should replace the found document. The document cannot contain any MongoDB update operators. |
Update Options options: <RemoteFindOneAndModifyOptions> |
Optional: A |
Sort RemoteFindOneAndModifyOptions.sort: <document> |
Optional. Specifies the query sort order. Sort documents
specify one or more fields to sort on where the value of each
field indicates whether MongoDB should sort it in ascending
( Example The following sort document specifies that documents should be
sorted first by |
Projection RemoteFindOneAndModifyOptions.projection: <document> |
Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query. To return all fields in the matching documents, omit this
parameter or specify an empty projection document ( To return specific fields and the document’s To withhold specific fields, specify the fields in the projection
document with a value of Note You may specify either fields to include or fields to withhold
but not both. For example, the following projection is
invalid because it simultaneously includes the The exception to this rule is the |
Upsert RemoteFindAndModifyOptions.upsert: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that MongoDB should insert a new document that
matches the query filter when the query does not match any
existing documents in the collection. |
Return New Document RemoteFindAndModifyOptions.returnNewDocument: <boolean> |
Optional. Default: false . A boolean that, if true ,
indicates that the action should return the document in its
post-replace form instead of its original form from before the
replace operation. |
completionHandler (StitchResult<CollectionType?>) -> Void |
Required. A completion handler that accepts StitchResult optional. This should be matched to check for successful completion of the operation |
Return Value¶
- Functions
- JavaScript SDK
- Android SDK
- iOS SDK
Note
You can specify whether to return the pre-replacement or
post-replacement version of the document by setting the value of
options.returnNewDocument
. By default, returnNewDocument
is
false
, which indicates that the promise should resolve to the
pre-update version of the document.
The collection.findOneAndReplace()
action returns a Promise that resolves to a
single document that the query overwrote. If no documents match the
specified query, the promise resolves to null
.
Note
You can specify whether to return the pre-replacement or
post-replacement version of the document by setting the value of
options.returnNewDocument
. By default, returnNewDocument
is
false
, which indicates that the promise should resolve to the
pre-update version of the document.
The collection.findOneAndReplace()
action returns a Promise that resolves to a
single document that the query overwrote. If no documents match the
specified query, the promise resolves to null
.
Note
You can specify whether to return the pre-replacement or
post-replacement version of the document by setting the value
of RemoteFindAndModifyOptions.returnNewDocument
. By
default, returnNewDocument
is false
, which indicates
that onComplete
should be called with a Task containing the
pre-update version of the document.
The findOneAndReplace()
function returns a
Task
containing the returned document, which can be accessed using
the task.getResult()
method. The type of the result
contained within the
Task
varies based on the configuration of the
RemoteMongoCollection
used for the operation and the value of the resultClass
parameter.
- If
resultClass
is specified, the returned Task contains an object of typeResultT
, which resolves to typeresultClass
. - If a
resultClass
is not specified, the returned Task contains an object of typeDocumentT
, which resolves to typeDocument
unless otherwise specified when the RemoteMongoCollection was instantiated. - If no document matches the provided query and the
upsert
option isfalse
,task.getResult()
will returnnull
. - If the operation fails for any other reason, the task will fail
and details can be accessed using
task.getException()
. If no
Note
You can specify whether to return the pre-replacement or
post-replacement version of the document by setting the value of
RemoteFindAndModifyOptions.returnNewDocument
. By default,
returnNewDocument
is false
, which indicates that
completionHandler
should be called with a StitchResult
containing the pre-update version of the document.
The findOneAndUpdate
method will call the supplied
completionHandler
with a StitchResult
.