Docs 菜单

Docs 主页 → 开发应用程序 → MongoDB Manual

db.collection.findOneAndReplace()

在此页面上

  • 定义
  • 语法
  • 行为
  • 举例

定义

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

重要

mongosh 方法

本页介绍了 mongosh方法。这不是数据库命令或特定语言驱动程序（例如 Node.js）的文档。

有关数据库命令，请参阅 update 命令。

对于 MongoDB API 驱动程序，请参阅特定语言的MongoDB 驱动程序文档。

对于传统 mongo Shell 文档，请参阅相应 MongoDB Server 版本的文档：

mongo shell v4.4

根据指定的筛选器替换单个文档。

语法

findOneAndReplace()方法采用以下形式：

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

字段和选项

findOneAndReplace()方法采用以下字段和选项：

字段
类型
说明
筛选器
文档

更新的选择条件。可以使用与 find() 方法中相同的查询选择器。

要替换集合中返回的第一个文档，请指定空文档{ }。

如果未指定，则默认为空文档。

从 MongoDB 4.2 开始，如果查询参数不是文档，则该操作将返回错误。

替换
文档

替换文档。

不能包含更新操作符。

<replacement> 文档无法指定与被替换文档不同的 _id 值。

writeConcern
文档

可选。表达写关注的文档。省略以使用默认写关注。

{ w: <value>, j: <boolean>, wtimeout: <number> }

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

投影
文档

可选。待返回字段的子集。

要返回匹配文档中的所有字段，请省略此字段。

从 MongoDB 4.2 开始，如果投影字段不是文档，则该操作将返回错误。

排序
文档

可选。指定筛选器匹配的文档的排序顺序。

从 MongoDB 4.2 开始，如果排序字段不是文档，则该操作将返回错误。

请参阅 cursor.sort()。

maxTimeMS
数字
可选。指定操作必须完成的时间限制（以毫秒为单位）。如果超出此限制，则会返回错误。
更新插入
布尔

可选。当true和findOneAndReplace()满足以下任一条件时：

  • 如果没有与 filter 匹配的文档，则插入 replacement 参数中的文档。插入新文档后返回 null，除非 returnNewDocument 是 true。

  • 将与 filter 匹配的文档替换为 replacement 文档。

如果 filter 和 replacement 文档中均未指定 _id 字段，MongoDB 会将该字段添加到替换文档中。如果 _id 存在于这两者中，则两个值必须相等。

要避免多次更新或插入，请确保 query 字段具有唯一索引。

默认值为 false。

returnDocument
字符串

可选。从mongosh 0开始。 13 。 2和returnDocument是returnNewDocument的替代方案。如果两个选项均已设置，则returnDocument优先。

returnDocument: "before" 返回原始文档。returnDocument: "after" 返回更新后的文档。

returnNewDocument
布尔

可选。为 true 时，会返回替换文档而不是原始文档。

默认值为 false。

排序规则
文档

可选。

指定用于操作的排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

排序规则选项的语法如下：

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

指定排序规则时，locale 字段为必填字段；所有其他排序规则字段均为可选字段。有关字段的说明，请参阅排序规则文档。

如果未指定排序规则，但集合具有默认排序规则（请参阅 db.createCollection()），则操作将使用为集合指定的排序规则。

如果没有为收集或操作指定排序规则，MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果执行带排序的查找，则不能使用一种排序规则进行查找而另一种排序规则进行排序。

返回：

默认返回原始文档。如果将returnDocument设置为after或将 returnNewDocument设置为true ，则返回更新后的文档。

行为

文档匹配

db.collection.findOneAndReplace()替换集合中与filter匹配的第一个匹配文档。 sort字段可用于影响修改哪个文档。

投射

重要

语言一致性

作为使find()和findAndModify()投影与聚合的$project阶段保持一致的一部分，

projection 字段采用以下格式的文档：

{ field1: <value>, field2: <value> ... }
投射
说明
<field>: <1 or true>
指定包含字段。如果为投影值指定非零整数，则该操作会将该值视为true。
<field>: <0 or false>
指定排除某个字段。
"<field>.$": <1 or true>

使用 $ 数组投影操作符返回与数组字段的查询条件匹配的第一个元素。如果您为该投影值指定非零整数，则该操作会将该值视为 true。

不可用于视图。

<field>: <array projection>

使用数组投影操作符（$elemMatch、$slice）指定要包含的数组元素。

不可用于视图。

<field>: <aggregation expression>

指定投影字段的值。

通过使用聚合表达式和语法（包括使用文字和聚合变量），您可以项目新字段或使用新值项目现有字段。

  • 如果您为投影值指定非数字、非布尔文字（例如文字字符串、数量或操作符表达式），则该字段将使用新值进行投影，例如：

    • { field: [ 1, 2, 3, "$someExistingField" ] }

    • { field: "New String Value" }

    • { field: { status: "Active", total: { $sum: "$existingArray" } } }

  • 要投影字段的字面值，请使用 $literal 聚合表达式，例如：

    • { field: { $literal: 5 } }

    • { field: { $literal: true } }

    • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }

在版本 4.2 及更早版本中，任何规范值（以前不支持的文档值除外）都被视作 true 或 false 以指示包含或排除该字段。

嵌入式字段规范

对于嵌入文档中的字段，您可以使用以下任一方式指定字段：

  • 点符号，例如 "field.nestedfield": <value>

  • 嵌套形式，例如 { field: { nestedfield: <value> } }

_id 字段投影

默认情况下，返回的文档中包含 _id 字段，除非您在投影中显式指定 _id: 0 来隐藏该字段。

包括或排除

projection 不能同时包含包含和排除规范，但 _id 字段除外：

  • 在显式包含字段的投影中，_id 字段是您可以显式排除的唯一字段。

  • 在明确排除字段的投影中，_id字段是您可以明确包含的唯一字段；但是，默认情况下包含_id字段。

有关投影的更多信息，另请参阅：

分片集合

要在分片集合上使用db.collection.findOneAndReplace() ，查询筛选器必须在分片键上包含相等条件。

文档在一个sharded collection中可能缺少分片键字段。要定位缺少分片键的文档，可以将null等值匹配与另一个筛选条件（例如针对_id字段）结合使用。例如：

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

分片键修改

从 MongoDB 4.2 开始，您可以更新文档的分片键值，除非分片键字段是不可变的 _id 字段。在 MongoDB 4.2 及更早版本中，文档的分片键字段值不可变的。

警告

在sharded collection中的文档可能缺少分片键字段。在更改文档的分片键值时，请采取预防措施，避免意外删除分片键。

要使用 修改 现有 分片键值：db.collection.findOneAndReplace()

  • 必须在 mongos 上运行。请勿直接对分片发出此操作。

  • 你必须在事务中运行，或者以可重试写入的形式运行。

  • 必须在完整分片键上包含相等筛选器。

缺少分片键

分片集合中的文档可能缺少分片键字段。要使用db.collection.findOneAndReplace()设置文档缺失的分片键，

  • 必须在 mongos 上运行。请勿直接对分片发出此操作。

  • 如果新的分片键值不是 null，则必须在事务中运行或作为可重试写入运行。

  • 必须在完整分片键上包含相等筛选器。

提示

由于缺失的键值是作为 null 相等匹配的一部分返回的，因此为避免更新空值键，请酌情纳入其他查询条件（例如 _id 字段）。

另请参阅：

事务

db.collection.findOneAndReplace()可以在分布式事务中使用。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在 ACID 事务中进行更新或插入 (upsert)

如果分布式事务不是跨分片写入事务，则可以在该事务中创建集合和索引。

db.collection.findOneAndReplace()和upsert: true可以在现有集合或不存在的集合上运行。如果在不存在的集合上运行，该操作将创建该集合。

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

Oplog 条目

如果db.collection.findOneAndReplace()操作成功替换文档，该操作则会在oplog （操作日志）上添加一个条目。如果操作失败或未找到要替换的文档，则不会在 oplog 上添加条目。

举例

替换文档

使用以下文档创建示例 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 }
]);

以下操作将查找score小于 20000 的文档并将其替换：

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

此操作会返回被替换的原始文档：

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

如果returnNewDocument为 true，则该操作将返回替换文档。

尽管有多个文档符合筛选条件，但db.collection.findOneAndReplace()仅替换一个文档。

对文档进行排序和替换

使用以下文档创建示例 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 }
]);

通过对score字段进行升序排序，以下示例将替换与筛选器匹配的文档中得分最低的文档：

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

此操作会返回被替换的原始文档：

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

有关此命令的未排序结果，请参阅替换文档。

返回文档中的项目特定字段

使用以下文档创建示例 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 }
])

以下操作使用投影仅显示返回文档中的team字段：

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

该操作返回仅包含 team 字段的原始文档：

{ "team" : "Cuddly Zebras" }

用 Time Limit 替换文档

以下操作设置了 5ms 的完成时间限制：

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

如果操作超过时间限制，将会返回：

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

使用更新插入操作替换文档

如果没有文档与 筛选器 匹配，以下操作将使用 更新 或插入字段插入替换文档：

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

该操作返回以下内容：

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

如果设置了 returnDocument: "before"，此操作则会返回 null，因为没有要返回的原始文档。

指定排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

使用以下文档创建示例 myColl 集合：

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

以下操作包括排序规则选项：

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

该操作将返回以下文档：

{ "_id" : 1, "category" : "café", "status" : "A" }
← db.collection.findOneAndDelete()
db.collection.findOneAndUpdate() →

在此页面上