db.collection.findOneAndReplace()

On this page本页内容

Definition定义

db.collection.findOneAndReplace(filter, replacement, options)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. 本页记录了mongo shell方法，未提及MongoDB Node.js驱动程序（或任何其他驱动程序）方法。For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.有关相应的MongoDB驱动程序API，请参阅特定的MongoDB驱动程序文档。

New in version 3.2.版本3.2中的新功能。

Replaces a single document based on the specified filter.根据指定的筛选器替换单个文档。

Syntax语法

The findOneAndReplace() method has the following form:findOneAndReplace()方法的形式如下：

db.collection.findOneAndReplace(
   <filter>,
   <replacement>,
   {
     projection: <document>,
     sort: <document>,
     maxTimeMS: <number>,
     upsert: <boolean>,
     returnNewDocument: <boolean>,
     collation: <document>
   }
)

Parameters and Options参数和选项

The findOneAndReplace() method takes the following parameters and options:findOneAndReplace()方法采用以下参数和选项：

Parameter参数Type类型Description描述
filter document

The selection criteria for the update. 更新的选择标准。The same query selectors as in the find() method are available.与find()方法中相同的查询选择器可用。

Specify an empty document { } to replace the first document returned in the collection.指定一个空文档{ }，以替换集合中返回的第一个文档。

If unspecified, defaults to an empty document.如果未指定，则默认为空文档。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the query argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果查询参数不是文档，则会出现操作错误。

replacement document

The replacement document.替换文件。

Cannot contain update operators.不能包含更新运算符。

The <replacement> document cannot specify an _id value that differs from the replaced document.<replacement>文档无法指定与被替换文档不同的_id值。

projection document

Optional. 可选。A subset of fields to return.要返回的字段的子集。

To return all fields in the matching document, omit this parameter.要返回匹配文档中的所有字段，请忽略此参数。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the projection argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果投影参数不是文档，则会出现操作错误。

sort document

Optional. 可选。Specifies a sorting order for the documents matched by the filter.为由filter匹配的文档指定排序顺序。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the sort argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果排序参数不是文档，则会出现操作错误。

See cursor.sort().请参见cursor.sort()。

maxTimeMS number Optional.可选。Specifies a time limit in milliseconds within which the operation must complete. 指定操作必须完成的时间限制（以毫秒为单位）。Throws an error if the limit is exceeded.如果超出限制，则引发错误。
upsert boolean

Optional. 可选。When true, findOneAndReplace() either:如果为true，则findOneAndReplace()可以：

  • Inserts the document from the replacement parameter if no document matches the filter. 如果没有与filter匹配的文档，则插入replacement参数中的文档。Returns null after inserting the new document, unless returnNewDocument is true.插入新文档后返回null，除非returnNewDocument为true。
  • Replaces the document that matches the filter with the replacement document.用替换文档替换与filter匹配的文档。

MongoDB will add the _id field to the replacement document if it is not specified in either the filter or replacement documents. 如果filter或replacement文档中未指定_id字段，MongoDB将向替换文档中添加该字段。If _id is present in both, the values must be equal.如果两者中都存在_id，则值必须相等。

To avoid multiple upserts, ensure that the query fields are uniquely indexed.要避免多个upsert，请确保query字段是唯一索引的。

Defaults to false.默认为false。

returnNewDocument boolean

Optional. 可选。When true, returns the replacement document instead of the original document.如果为true，则返回替换文档，而不是原始文档。

Defaults to false.默认为false。

collation document

Optional.可选。

Specifies the collation to use for the operation.指定要用于该操作的排序规则。

Collation排序规则 allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号的规则。

The collation option has the following syntax:collation选项语法如下所示：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

When specifying collation, the locale field is mandatory; all other collation fields are optional. 指定排序规则时，locale字段是必需的；所有其他排序规则字段都是可选的。For descriptions of the fields, see Collation Document.有关这些字段的描述，请参阅排序规则文档。

If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection.如果未指定排序规则，但集合具有默认排序规则（请参见db.createCollection()），则操作将使用为集合指定的排序规则。

If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.如果没有为集合或操作指定排序规则，MongoDB将使用以前版本中用于字符串比较的简单二进制比较。

You cannot specify multiple collations for an operation. 不能为一个操作指定多个排序规则。For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.例如，不能为每个字段指定不同的排序规则，或者如果使用排序执行查找，则不能对查找使用一种排序规则，对排序使用另一种排序规则。

New in version 3.4.版本3.4中的新功能。

Returns返回

Returns either the original document or, if returnNewDocument: true, the replacement document.返回原始文档，如果returnNewDocument:true，则返回替换文档。

Behavior行为

Document Match文档匹配

db.collection.findOneAndReplace() replaces the first matching document in the collection that matches the filter. 替换集合中与filter匹配的第一个匹配文档。The sort parameter can be used to influence which document is modified.sort参数可用于影响修改的文档。

Projection预测

Language Consistency语言一致性

Starting in MongoDB 4.4, as part of making find and findAndModify projection consistent with aggregation’s $project stage,从MongoDB 4.4开始，作为使find和findAndModify投影与聚合的$project阶段保持一致的一部分，

The projection parameter takes a document in the following form:projection参数采用以下形式的文档：

{ field1: <value>, field2: <value> ... }
Projection投影Description描述
<field>: <1 or true> Specifies the inclusion of a field.指定字段的包含。
<field>: <0 or false> Specifies the exclusion of a field.指定字段的排除。
"<field>.$": <1 or true> With the use of the $ array projection operator, you can specify the projection to return the first element that match the query condition on the array field; e.g. "arrayField.$" : 1. 使用$数组投影运算符，可以指定投影以返回与数组字段上的查询条件匹配的第一个元素；例如，"arrayField.$" : 1。(Not available for views.)（不适用于视图。）
<field>: <array projection> Using the array projection operators $elemMatch, $slice, specifies the array element(s) to include, thereby excluding those elements that do not meet the expressions. 使用数组投影运算符$elemMatch，$slice，指定要包含的数组元素，从而排除那些不符合表达式的元素。(Not available for views.)（不适用于视图。）
<field>: <aggregation expression>

Specifies the value of the projected field.指定投影字段的值。

Starting in MongoDB 4.4, with the use of aggregation expressions and syntax, including the use of literals and aggregation variables, you can project new fields or project existing fields with new values. 从MongoDB 4.4开始，通过使用聚合表达式和语法，包括使用文字和聚合变量，可以投影新字段或使用新值投影现有字段。For example,例如

  • If you specify a non-numeric, non-boolean literal (such as a literal string or an array or an operator expression) for the projection value, the field is projected with the new value; e.g.:如果为投影值指定非数字、非布尔文字（例如文字字符串、数组或运算符表达式），则会使用新值投影字段；如：
    • { field: [ 1, 2, 3, "$someExistingField" ] }
    • { field: "New String Value" }
    • { field: { status: "Active", total: { $sum: "$existingArray" } } }
  • To project a literal value for a field, use the $literal aggregation expression; e.g.:要为字段投影文字值，请使用$literal聚合表达式；如。：
    • { field: { $literal: 5 } }
    • { field: { $literal: true } }
    • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }

In versions 4.2 and earlier, any specification value (with the exception of the previously unsupported document value) is treated as either true or false to indicate the inclusion or exclusion of the field.在版本4.2和更早版本中，任何规范值（以前不支持的文档值除外）都被视为true或false，以指示包含或排除该字段。

New in version 4.4.版本4.4中的新功能。

Embedded Field Specification嵌入式字段规范

For fields in an embedded documents, you can specify the field using either:对于嵌入文档中的字段，可以使用以下任一方法指定字段：

  • dot notation; e.g. 点符号；如："field.nestedfield": <value>
  • nested form; e.g. 嵌套形式；如：{ field: { nestedfield: <value> } } (Starting in MongoDB 4.4)

_id Field Projection字段投影

The _id field is included in the returned documents by default unless you explicitly specify _id: 0 in the projection to suppress the field.默认情况下，_id字段包含在返回的文档中，除非在投影中明确指定_id: 0以抑制该字段。

Inclusion or Exclusion包含还是排除

A projection cannot contain both include and exclude specifications, with the exception of the _id field:projection不能同时包含包含和排除规范，但_id字段除外：

  • In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.在显式包含字段的投影中，_id字段是唯一可以显式排除的字段。
  • In projections that explicitly excludes fields, the _id field is the only field that you can explicitly include; however, the _id field is included by default.在显式排除字段的投影中，_id字段是唯一可以显式包括的字段；但是，默认情况下会包含_id字段。

For more information on projection, see also:有关投影的更多信息，请参阅：

Sharded Collections分片集合

To use db.collection.findOneAndReplace() on a sharded collection, the query filter must include an equality condition on the shard key.要在分片集合上使用db.collection.findOneAndReplace()，查询筛选器必须在分片键上包含相等条件。

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，切分集合中的文档可能会缺少切分键字段。To target a document that is missing the shard key, you can use the null equality match in conjunction with another filter condition (such as on the _id field). 要将缺少切分键的文档作为目标，可以将null相等匹配与另一个筛选条件结合使用（例如在_id字段上）。For example:例如：

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Shard Key Modification分片键修改

Starting in MongoDB 4.2, you can update a document’s shard key value unless the shard key field is the immutable _id field. 从MongoDB 4.2开始，可以更新文档的分片键值，除非分片键字段是不可变的_id字段。Before MongoDB 4.2, a document’s shard key field value is immutable.在MongoDB 4.2之前，文档的分片键字段值是不可变的。

Warning警告

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. 从4.4版开始，分片集合中的文档可能会缺少分片键字段。Take precaution to avoid accidentally removing the shard key when changing a document’s shard key value.采取预防措施，以避免在更改文档的分片键值时意外删除分片键。

To modify the existing shard key value with db.collection.findOneAndReplace():要使用db.collection.findOneAndReplace()修改现有的碎片键值，请执行以下操作：

  • You must run on a mongos. 你必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在分片上发布操作。
  • You must run either in a transaction or as a retryable write.您必须在事务中运行，或作为可重试写入运行。
  • You must include an equality filter on the full shard key.必须在完整分片键上包含相等筛选器。

Missing Shard Key缺少分片键

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，分片集合中的文档可能会缺少分片键字段。To use db.collection.findOneAndReplace() to set the document’s missing shard key,要使用db.collection.findOneAndReplace()设置文档缺少的分片键，

  • You must run on a mongos. 你必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在分片上发布操作。
  • You must run either in a transaction or as a retryable write if the new shard key value is not null.如果新的分片键值不为null，则必须在事务中或作为可重试写入运行。
  • You must include an equality filter on the full shard key.必须在完整分片键上包含相等筛选器。

Tip

Since a missing key value is returned as part of a null equality match, to avoid updating a null-valued key, include additional query conditions (such as on the _id field) as appropriate.由于缺少的键值是作为空相等匹配的一部分返回的，为了避免更新空值键值，请酌情包括其他查询条件（例如在_id字段上）。

See also:

Transactions事务

db.collection.findOneAndReplace() can be used inside multi-document transactions.可以在多文档事务中使用。

Important

In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. 在大多数情况下，与单文档写入相比，多文档事务会带来更大的性能成本，而多文档事务的可用性不应取代有效的模式设计。For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. 对于许多场景，非规范化数据模型（嵌入式文档和数组）将继续适合您的数据和用例。That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.也就是说，对于许多场景，适当地建模数据将最大限度地减少对多文档事务的需求。

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.有关其他事务使用注意事项（如运行时限制和oplog大小限制），请参阅生产注意事项。

Upsert within Transactions在事务中插入

Starting in MongoDB 4.4 with feature compatibility version (fcv) "4.4", you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.从功能兼容版本（fcv）"4.4"的MongoDB 4.4开始，如果事务不是跨切分写入事务，则可以在多文档事务中创建集合和索引。

As such, for the feature compatibility version (fcv) is "4.4" or greater, db.collection.findOneAndReplace() with upsert: true can be run against an existing collection or a non-existing collection. 因此，对于功能兼容性版本（fcv）为"4.4"或更高版本的情况，可以对现有集合或不存在的集合运行带有upsert:true的db.collection.findOneAndReplace()。If run against a non-existing collection, the operation creates the collection.如果针对不存在的集合运行，该操作将创建该集合。

If the feature compatibility version (fcv) is "4.2" or less, the operation must be against an existing collection.如果功能兼容版本（fcv）为"4.2"或更低，则操作必须针对现有集合。

See also参阅

Create Collections and Indexes In a Transaction在事务中创建集合和索引

Write Concerns and Transactions撰写关注事项和交易记录

Do not explicitly set the write concern for the operation if run in a transaction. 如果在事务中运行，请不要显式设置操作的写入关注点。To use write concern with transactions, see Transactions and Write Concern.要将写关注点用于事务，请参阅事务和写关注点。

Examples示例

Replace A Document替换文件

Create a sample scores collection with the following documents:使用以下文档创建一个样本scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

The following operation finds a document with score less than 20000 and replaces it:以下操作将查找scores小于20000的文档并将其替换：

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 }
)

The operation returns the original document that has been replaced:该操作将返回已替换的原始文档：

{ "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }

If returnNewDocument was true, the operation would return the replacement document instead.如果returnNewDocument为true，则操作将返回替换文档。

Although multiple documents meet the filter criteria, db.collection.findOneAndReplace replaces only one document.虽然多个文档满足筛选条件，但db.collection.findOneAndReplace只替换一个文档。

Sort and Replace A Document对文档进行排序和替换

Create a sample scores collection with the following documents:使用以下文档创建一个样本scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

By including an ascending sort on the score field, the following example replaces the document with the lowest score among those documents that match the filter:通过在score字段中包含升序排序，以下示例将文档替换为与filter匹配的文档中分数最低的文档：

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 },
   { sort: { "score" : 1 } }
)

The operation returns the original document that has been replaced:该操作将返回已替换的原始文档：

{ "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }

See Replace A Document for the non-sorted result of this command.有关此命令的未排序结果，请参阅替换文档。

Project Specific Fields in Return Document返回文档中的项目特定字段

Create a sample scores collection with the following documents:使用以下文档创建一个样本scores集合：

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
])

The following operation uses projection to only display the team field in the returned document:以下操作使用projection仅显示返回文档中的team字段：

db.scores.findOneAndReplace(
   { "score" : { $lt : 22250 } },
   { "team" : "Therapeutic Hamsters", "score" : 22250 },
   { sort : { "score" : 1 }, projection: { "_id" : 0, "team" : 1 } }
)

The operation returns the original document with only the team field:该操作返回原始文档，其中仅包含team字段：

{ "team" : "Cuddly Zebras" }

Replace Document with Time Limit用时限代替文件

The following operation sets a 5ms time limit to complete:以下操作设置了5毫秒的完成时间限制：

try {
   db.scores.findOneAndReplace(
      { "score" : { $gt : 25000 } },
      { "team" : "Emphatic Rhinos", "score" : 25010 },
      { maxTimeMS: 5 }
   );
} catch(e){
   print(e);
}

If the operation exceeds the time limit, it returns:如果操作超过时间限制，则返回：

Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }

Replace Document with Upsert用Upsert替换文档

The following operation uses the upsert field to insert the replacement document if no document matches the filter:如果没有与filter匹配的文档，以下操作将使用upsert字段插入替换文档：

try {
   db.scores.findOneAndReplace(
      { "team" : "Fortified Lobsters" },
      { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000},
      { upsert : true, returnNewDocument: true }
   );
} catch (e){
   print(e);
}

The operation returns the following:该操作返回以下内容：

{
   "_id" : 6019,
   "team" : "Fortified Lobsters",
   "score" : 32000
}

If returnNewDocument was false, the operation would return null as there is no original document to return.如果returnNewDocument为false，操作将返回null，因为没有要返回的原始文档。

Specify Collation指定排序规则

New in version 3.4.版本3.4中的新功能。

Collation排序规则 allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号的规则。

Create a sample myColl collection with the following documents:使用以下文档创建myColl样本集合：

db.myColl.insertMany([
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
]);

The following operation includes the collation option:以下操作包括排序规则选项：

db.myColl.findOneAndReplace(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

The operation returns the following document:该操作将返回以下文档：

{ "_id" : 1, "category" : "café", "status" : "A" }