Navigation

collection.findOneAndReplace()

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

To call the collection.findOneAndUpdate() action from a Function, get a collection handle with database.collection() then call the handle’s findOneAndUpdate() method.

// Find the document that describes "legos"
const query = { "name": "legos" };
// Replace it with a new document
const replacement = {
    "name": "blocks",
    "price": 20.99,
    "category": "toys"
};
// Return the original document as it was before being replaced
const options = { "returnNewDocument": false };

return itemsCollection.findOneAndReplace(query, replacement, options)
  .then(replacedDocument => {
    if(replacedDocument) {
      console.log(`Successfully replaced the following document: ${replacedDocument}.`)
    } else {
      console.log("No document matches the provided query.")
    }
    return updatedDocument
  })
  .catch(err => console.error(`Failed to find and replace document: ${err}`))

To call the collection.findOneAndReplace() action from a JavaScript SDK, use the RemoteMongoCollection.findOneAndReplace() method.

// Find the document that describes "legos"
const query = { "name": "legos" };
// Replace it with a new document
const replacement = {
    "name": "blocks",
    "price": 20.99,
    "category": "toys"
};
// Return the original document as it was before being replaced
const options = { "returnNewDocument": false };

itemsCollection.findOneAndReplace(query, replacement, options)
  .then(replacedDocument => {
    if(replacedDocument) {
      console.log(`Successfully replaced the following document: ${replacedDocument}.`)
    } else {
      console.log("No document matches the provided query.")
    }
    return updatedDocument
  })
  .catch(err => console.error(`Failed to find and replace document: ${err}`))

Note

The collection.findOneAndReplace() action is currently only available in Functions, JavaScript, and iOS SDKs.

let query: Document = ["name": "blocks"]
// MongoDB recommends monetary data be stored as Decimal128
let replacement: Document = ["name": "legos",
                             "price": Decimal128("22.99"),
                             "category": "education"]
// return the document in its updated form
let options = RemoteFindOneAndModifyOptions(returnNewDocument: true)
itemsCollection?.findOneAndReplace(filter: query, replacement: replacement, options: options) { result in
    switch result {
    case .success(let doc):
        switch doc {
        case .none:
            print("No document matches the provided query")
        case .some(let doc):
            print("Successfully replaced document: \(doc)")
        }
    case .failure(let err):
        print("Failed to findOneAndReplace: \(err)")
    }
}

Parameters

The collection.findOneAndReplace() action has the following form:

findOneAndReplace(query, replacement, options)
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 options document has the following form:

{
   "upsert": <boolean>,
   "sort": <document>,
   "projection": <document>,
   "returnNewDocument": <boolean>
}

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 (1) or descending (0) order. The sort order determines which document collection.findOneAndReplace() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

{ age: 0, name: 1 }

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 _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
{ <Field Name>: 1 }

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
{ <Field Name>: 0 }

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 name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
{ "name": 1, "address": 0 }

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
{ "_id": 0, "name": 1 }

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:

findOneAndReplace(query, replacement, options)
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 options document has the following form:

{
   "upsert": <boolean>,
   "sort": <document>,
   "projection": <document>,
   "returnNewDocument": <boolean>
}

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 (1) or descending (0) order. The sort order determines which document collection.findOneAndReplace() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

{ age: 0, name: 1 }

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 _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
{ <Field Name>: 1 }

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
{ <Field Name>: 0 }

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 name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
{ "name": 1, "address": 0 }

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
{ "_id": 0, "name": 1 }

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.

Note

The collection.findOneAndReplace() action is currently only available in Functions, JavaScript, and iOS SDKs.

public func findOneAndReplace(filter: Document,
                   replacement: Document,
                   options: RemoteFindOneAndModifyOptions? = nil,
                   _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)
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.

Replace Operation

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 RemoteFindOneAndModifyOptions> struct that can be initialized with the following values.

RemoteFindOneAndModifyOptions.init(
    "sort": <document>,
    "projection": <document>,
    "upsert": <bool>,
    "returnNewDocument": <bool>
)

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 (1) or descending (0) order. The sort order determines which document collection.findOneAndUpdate() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

[ "age": 0, "name": 1 ]

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 _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
[ <Field Name>: 1 ]

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
[ <Field Name>: 0 ]

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 name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
[ "name": 1, "address": 0 ]

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
[ "_id": 0, "name": 1 ]

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

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.

Promise<document|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.

Promise<document|null>

Note

The collection.findOne() action is currently only available in Functions, JavaScript and iOS SDKs.

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.