db.collection.findOneAndUpdate()

在此页面上

定义

兼容性
语法
行为
示例

带驱动程序的 MongoDB

本页面提供 mongosh 方法的相关信息。要查看 MongoDB 驱动程序中的等效方法，请参阅编程语言的相应页面：

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

定义

db.collection.findOneAndUpdate( filter, update, options )

根据 filter 和 sort 标准更新单个文档。

提示

8.0 版本中的新增功能：updateOne() 方法包含一个 sort 选项，用于按用户指定的排序顺序更新第一个文档。

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

兼容性

此方法可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

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

db.collection.findOneAndUpdate(
    <filter>,
    <update document or aggregation pipeline>,
    {
      writeConcern: <document>,
      projection: <document>,
      sort: <document>,
      maxTimeMS: <number>,
      upsert: <boolean>,
      returnDocument: <string>,
      returnNewDocument: <boolean>,
      collation: <document>,
      arrayFilters: [ <filterdocument1>, ... ]
    }
)

findOneAndUpdate() 方法使用以下参数：

Parameter

类型

说明

filter

文档

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

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

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

如果查询字段不是文档，则操作将返回错误。

如果没有文档与 filter 匹配，则不更新任何文档。

update

文档或数组

更新文档或聚合管道。

如果传递了带有更新操作符表达式的文档， db.collection.findOneAndUpdate()则会执行指定的修改。
该文档必须只包含更新操作符。您无法指定替换文档 { <field1>: <value1>, ...}。要使用替换文档，请参阅 db.collection.findOneAndReplace()。
如果传递了聚合管道[ <stage1>, <stage2>, ... ] ，则db.collection.findOneAndUpdate() 将修改每个管道的文档。该管道可以由以下阶段组成：
- $addFields 及其别名 $set
- $project 及其别名 $unset
- $replaceRoot 及其别名 $replaceWith。

writeConcern

文档

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

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

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

projection

文档

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

如要返回返回文档中的所有字段，请忽略此参数。

如果投影参数不是文档，则操作会出错。

sort

文档

可选。为 filter 所匹配的文档指定排序顺序。

如果 sort 参数不是文档，则操作错误。

请参阅 cursor.sort()。

maxTimeMS

数字

可选。指定该操作必须完成的时间限制（以毫秒为单位）。如果超出此限制，则会返回错误。

upsert

布尔

可选。当true findOneAndUpdate()时，将：

如果没有文档与 filter 匹配，则创建一个新文档。有关详细信息，请参阅更新或插入行为。插入新文档后返回 null，除非 returnNewDocument 是 true。
更新与 filter 匹配的单份文档。

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

默认值为 false；即，在未找到匹配项时不插入新文档。

returnDocument

字符串

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

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

returnNewDocument

布尔

可选。当值为 true 时，返回更新后的文档而非原始文档。

默认值为 false。

collation

文档

可选。

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

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

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

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

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

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

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

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

arrayFilters

阵列

选修的。大量过滤器文档，用于确定针对大量字段的更新操作要修改哪些大量元素。

在更新文档中，使用 $[<identifier>] 筛选后的位置运算符来定义标识符，然后在数组筛选文档中引用该标识符。如果更新文档中未包含某一标识符，则无法获得该标识符的数组筛选文档。

<identifier> 必须以小写字母开头，且只能包含字母数字字符。

您可以在更新文档中多次包含相同的标识符；但对于更新文档中的每个不同标识符 ($[identifier])，您必须准确指定一个对应的数组筛选器文档。也就是说，不能为同一个标识符指定多个数组筛选器文档。例如，如果更新语句包含标识符 x（可能多次），则不能为 arrayFilters 指定以下内容，其中包括 x 的 2 个单独的筛选器文档：

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

但是，您可以在单个过滤器文档中的同一标识符上指定复合条件，例如以下示例：

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

有关示例，请参阅使用 arrayFilters进行数组更新操作。

arrayFilters 不适用于使用聚合管道的更新。

行为

性能

可重试写入需要 findOneAndUpdate() 方法在执行更新之前将整个文档复制到副本集中每个节点的特殊端集合中。这会使 findOneAndUpdate() 在处理大型文档或大型副本集时成为一项昂贵的操作。

8.0 版本中的新增功能：要按用户定义的顺序更新第一个文档并获得更好的性能，请使用带有sort 选项的 db.collection.updateOne() 方法。

文档匹配

db.collection.findOneAndUpdate() 更新集合中与 filter 匹配的第一个文档。如果没有文档与 filter 匹配，则不会更新任何文档。

sort 参数可用于对更新哪个文档施加影响。

投射

重要

语言一致性

在调整 find() 和 findAndModify() 投影以便与聚合的 $project 阶段保持一致的过程中：

find() 和 findAndModify() 投影可以接受聚合表达式和事务语法。
MongoDB 对投影执行额外的限制。有关详细信息，请参阅投影限制。

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 } } }`

嵌入式字段规范

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

点符号，例如 "field.nestedfield": <value>
嵌套表单，例如 { field: { nestedfield: <value> } }

`_id` 字段投影

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

包括或排除

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

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

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

查询返回的项目字段

分片集合

分片集合中的文档可能缺少分片键字段。要定位缺失分片键的文档，可将 null 等值匹配与其他过滤条件（例如针对 _id 字段）结合使用。例如：

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

分片键修改

您可以更新文档的分片键值，除非分片键字段是不可变的 _id 字段。

警告

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

要修改现有的分片键值（使用db.collection.findOneAndUpdate()）：

必须在 mongos 上运行。请勿直接对分片发出此操作。
你必须在事务中运行，或者以可重试写入的形式运行。
必须在完整分片键上包含相等筛选器。

缺少分片键

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

必须在 mongos 上运行。请勿直接对分片发出此操作。
如果新的分片键值不是 null，则必须在事务中运行或作为可重试写入运行。
必须在完整分片键上包含相等筛选器。

提示

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

另请参阅：

缺少的分片键字段

事务

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

重要

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

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

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

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

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

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

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

Oplog 条目

如果 db.collection.findOneAndUpdate() 操作成功更新了文档，则该操作会为 oplog（操作日志）添加一个条目。如果操作失败或者未找到要更新的文档，则该操作不会为 oplog 添加条目。

示例

更新文档

grades 集合包含类似于以下格式的文档：

{ _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 },
{ _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 },
{ _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 },
{ _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 },
{ _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 },
{ _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 }

以下操作会查找第一个文档，其中 name : R. Stiles，且得分递增 5：

db.grades.findOneAndUpdate(
   { "name" : "R. Stiles" },
   { $inc: { "points" : 5 } }
)

该操作在更新之前返回原始文档：

{ _id: 6319, name: "R. Stiles", "assignment" : 2, "points" : 12 }

如果 returnNewDocument 为 true，此操作会返回更新后的文档。

对文档进行排序和更新

grades 集合包含类似于以下格式的文档：

{ _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 },
{ _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 },
{ _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 },
{ _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 },
{ _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 },
{ _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 }

以下操作将更新 name : "A. MacDyver" 的文档。该操作按 points 升序对匹配文档进行排序，以更新具有最少点数的匹配文档。

db.grades.findOneAndUpdate(
   { "name" : "A. MacDyver" },
   { $inc : { "points" : 5 } },
   { sort : { "points" : 1 } }
)

该操作在更新之前返回原始文档：

{ _id: 6322, name: "A. MacDyver", "assignment" : 2, "points" : 14 }

投影返回的文档

以下操作使用投影以仅显示返回文档中的 _id、points 和 assignment 字段：

db.grades.findOneAndUpdate(
   { "name" : "A. MacDyver" },
   { $inc : { "points" : 5 } },
   { sort : { "points" : 1 }, projection: { "assignment" : 1, "points" : 1 } }
)

该操作返回仅包含 projection 文档和 _id 字段中指定的字段的原始文档，因为它在投影文档中未显式抑制 ( _id: 0 ) 。

{ "_id" : 6322, "assignment" : 2, "points" : 14 }

在有时间限制的情况下更新文档

以下操作设置 5 毫秒的时间限制来完成更新：

try {
   db.grades.findOneAndUpdate(
      { "name" : "A. MacDyver" },
      { $inc : { "points" : 5 } },
      { sort: { "points" : 1 }, maxTimeMS : 5 };
   );
}
catch(e){
   print(e);
}

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

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

使用更新或插入更新文档

如果没有内容匹配 filter，则以下操作使用 upsert 字段插入更新文档：

try {
db.grades.findOneAndUpdate(
   { "name" : "A.B. Abracus" },
   { $set: { "name" : "A.B. Abracus", "assignment" : 5}, $inc : { "points" : 5 } },
   { sort: { "points" : 1 }, upsert:true, returnNewDocument : true }
);
}
catch (e){
   print(e);
}

该操作返回以下内容：

{
   "_id" : ObjectId("5789249f1c49e39a8adc479a"),
   "name" : "A.B. Abracus",
   "assignment" : 5,
   "points" : 5
}

如果 returnNewDocument 为 false，则该操作返回 null，因为没有要返回的原始文档。

指定排序规则。

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

集合 myColl 包含以下文档：

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

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

db.myColl.findOneAndUpdate(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

该操作将返回以下文档：

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

数组更新操作 `arrayFilters`

注意

arrayFilters 不适用于使用聚合管道的更新。

更新数组字段时，您可以指定 arrayFilters 确定要更新哪些数组元素。

更新元素匹配 `arrayFilters` 条件

注意

arrayFilters 不适用于使用聚合管道的更新。

使用以下文档创建集合 students：

db.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

如要修改 grades 数组中所有大于或等于 100 的元素，请使用经过滤的位置操作符 $[<identifier>] 和 db.collection.findOneAndUpdate() 方法中的 arrayFilters 选项：

db.students.findOneAndUpdate(
   { grades: { $gte: 100 } },
   { $set: { "grades.$[element]" : 100 } },
   { arrayFilters: [ { "element": { $gte: 100 } } ] }
)

该操作更新单个文档的 grades 字段，完成该操作后，集合中将包含以下文档：

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 110, 100 ] }

更新文档数组的特定元素

注意

arrayFilters 不适用于使用聚合管道的更新。

使用以下文档创建集合 students2：

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

以下操作查找 _id 字段等于 1 的文档，并使用通过 arrayFilters 筛选后的位置操作符 $[<identifier>] 来修改 grades 数组中成绩大于等于 85 的所有元素的 mean。

db.students2.findOneAndUpdate(
   { _id : 1 },
   { $set: { "grades.$[elem].mean" : 100 } },
   { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
)

该操作更新单个文档的 grades 字段，完成该操作后，集合中将包含以下文档：

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
    ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}

使用聚合管道进行更新

db.collection.findOneAndUpdate() 可以接受聚合管道以用于更新。该管道可以由以下阶段组成：

使用聚合分析管道可以进行更具表现力的更新声明，例如基于当前字段值的Express条件更新或使用另一个字段的值更新一个字段。

例如，使用以下文档创建名为 students2 的集合：

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

以下操作查找 _id 字段等于 1 的文档，并使用聚合管道根据 grades 字段计算新字段 total 的值：

db.students2.findOneAndUpdate(
   { _id : 1 },
   [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   { returnNewDocument: true }
)

注意

管道中使用的 $set 指的是聚合阶段 $set 而不是更新操作符 $set。

该操作返回更新后的文档：

{
  "_id" : 1,
  "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" :85, "std" : 6 } ],
  "total" : 250
}

后退

db.collection.findOneAndReplace()

来年

db.collection.getIndexes

定义

提示

兼容性

注意

语法

行为

性能

文档匹配

投射

重要

语言一致性

嵌入式字段规范

_id 字段投影

包括或排除

分片集合

分片键修改

警告

缺少分片键

提示

事务

重要

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

提示

另请参阅：

写关注和事务

Oplog 条目

示例

更新文档

对文档进行排序和更新

投影返回的文档

在有时间限制的情况下更新文档

使用更新或插入更新文档

指定排序规则。

数组更新操作 arrayFilters

注意

更新元素匹配 arrayFilters 条件

注意

更新文档数组的特定元素

注意

使用聚合管道进行更新

注意

`_id` 字段投影

数组更新操作 `arrayFilters`

更新元素匹配 `arrayFilters` 条件