db.collection.findOneAndUpdate（）

MongoDB 中文手册

参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.findOneAndUpdate（）

在本页面

定义
行为
例子

定义¶

db.collection.findOneAndUpdate（filter，update，options ）¶

mongo 壳法

此页面记录了mongoshell方法，并且没有引用MongoDB Node.js驱动程序（或任何其他驱动程序）方法。对于相应的MongoDB驱动程序API，请改为参考您特定的 MongoDB驱动程序文档。

3.2版中的新功能。

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

该findOneAndUpdate()方法具有以下形式：

复制

db.collection.findOneAndUpdate(
   <filter>,
   <update document or aggregation pipeline>, // Changed in MongoDB 4.2
   {
     projection: <document>,
     sort: <document>,
     maxTimeMS: <number>,
     upsert: <boolean>,
     returnNewDocument: <boolean>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ]
   }
)

该findOneAndUpdate()方法采用以下参数：

参数	类型	描述
`filter`	文献	更新的选择标准。提供与方法中相同的查询选择器 `find()`。指定一个空文档以更新集合中返回的第一个文档。`{ }` 如果未指定，则默认为空文档。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果查询参数不是文档，则操作错误。
`update`	文件或阵列	更新文档，或者从MongoDB 4.2开始的聚合管道。如果传递带有update运算符表达式的文档，则`db.collection.findOneAndUpdate()`执行指定的修改。注意该文档必须仅包含更新运算符表达式。您不能指定替换文档。要使用替换文档，请参阅。`{ <field1>: <value1>, ...}db.collection.findOneAndReplace()` 在MongoDB中4.2开始，如果通过一个汇聚管道，修改每个管道中的文档。管道可以包括以下阶段：`[ <stage1>, <stage2>, ... ]db.collection.findOneAndUpdate()` `$addFields` 及其别名 `$set` `$project` 及其别名 `$unset` `$replaceRoot`及其别名`$replaceWith`。
`projection`	文献	可选的。要返回的字段子集。要返回返回文档中的所有字段，请省略此参数。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果projection参数不是文档，则操作会出错。
`sort`	文献	可选的。指定与匹配的文档的排序顺序`filter`。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果sort参数不是文档，则操作会出错。请参阅`cursor.sort()`。
`maxTimeMS`	数	可选的。指定操作必须在其内完成的时间限制（以毫秒为单位）。如果超出限制，则会引发错误。
`upsert`	布尔值	可选的。当`true`，`findOneAndUpdate()`要么：如果没有文档与匹配，则创建一个新文档`filter`。有关更多详细信息，请参见upsert行为。`null`插入新文档后返回，除非`returnNewDocument`是`true`。更新与匹配的单个文档`filter`。为避免多次更新，请确保`filter`字段被唯一索引。默认为`false`。
`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使用先前版本中使用的简单二进制比较进行字符串比较。您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。 3.4版的新功能。
`arrayFilters`	数组	可选的。筛选器文档数组，用于确定要对数组字段进行更新操作要修改的数组元素。在更新文档中，使用`$[<identifier>]`过滤后的位置运算符定义一个标识符，然后在数组过滤器文档中引用该标识符。如果该标识符未包含在更新文档中，则不能具有标识符的数组过滤器文档。注意在`<identifier>`必须以小写字母开头，并且只包含字母数字字符。您可以在更新文档中多次包含相同的标识符；但是，对于`$[identifier]`更新文档中的每个不同的标识符（），必须精确地指定一个对应的数组过滤器文档。也就是说，您不能为同一标识符指定多个数组过滤器文档。例如，如果update语句包含标识符`x` （可能多次），则不能为以下内容指定以下内容 `arrayFilters`：包括2个单独的过滤器文档`x`： // 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` 不适用于使用聚合管道的更新。 3.6版的新功能。

返回值：	返回原始文档，或者如果更新的文档，则返回。`returnNewDocument: true`

行为¶

单证相符¶

db.collection.findOneAndUpdate()更新集合中与匹配的第一个匹配文档filter。该sort参数可用于影响哪个文档被更新。

投影¶

该projection参数采用以下格式的文档：

复制

{ field1 : < boolean >, field2 : < boolean> ... }

该<boolean>值可以是以下任意值：

1或true包含该字段。_id即使未在projection参数中明确说明该方法，该方法也会返回该字段。
0或false排除该字段。可以在任何字段（包括）上使用_id。

分片集合¶

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

碎片键修改¶

从MongoDB 4.2开始，除非分片键字段是不可变_id字段，否则您可以更新文档的分片键值。有关更新分片键的详细信息，请参阅“ 更改文档的分片键值”。

在MongoDB 4.2之前，文档的分片键字段值是不可变的。

要用于 db.collection.findOneAndUpdate()更新分片键：

您必须在运行mongos无论是在交易或作为重试写。千万不能直接在碎片颁发运行。
您必须在查询过滤器中的完整分片键上包含相等条件。例如，如果一个集合messages 使用的片键，更新为一个文件的碎片关键，你必须包括在查询过滤器。您可以根据需要在查询中包括其他字段。{ country : 1, userid : 1 }country: <value>, userid: <value>

交易¶

db.collection.findOneAndUpdate()可以在多文档交易中使用。

重要

在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应代替有效的架构设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）对于您的数据和用例将继续是最佳的。也就是说，在许多情况下，对数据进行适当的建模将最大程度地减少对多文档交易的需求。

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

现有的收藏和交易¶

在事务内部，您可以指定对现有集合的读/写操作。如果db.collection.findOneAndUpdate()导致upsert，则该集合必须已经存在。

如果该操作导致upsert，则该集合必须已经存在。

写的担忧和事务¶

如果在事务中运行，则不要为操作明确设置写关注点。要对事务使用写关注，请参见事务和写关注。

例子¶

在这个部分

更新文件
排序和更新文档
投影退回的文件
有时间限制更新文件
使用Upsert更新文档
指定排序规则
阵列更新操作 arrayFilters
使用汇总管道进行更新

更新文件¶

该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. Stiles5

复制

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 }

更新文档有时间限制¶

以下操作将5ms的时间限制设置为完成更新：

复制

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 }

使用Upsert更新文档¶

upsert如果没有任何匹配项，以下操作将使用该字段插入更新文档filter：

复制

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为假，操作将返回，null因为没有原始文档要返回。

指定归类¶

3.4版的新功能。

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

集合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 不适用于使用聚合管道的更新。

3.6版的新功能。

从MongoDB 3.6开始，在更新数组字段时，您可以指定arrayFilters确定要更新的数组元素。

更新元素匹配`arrayFilters`条件¶

注意

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

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

复制

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

要修改是大于或等于所有元素100中 grades阵列中，使用过滤的位置操作者 $[<identifier>]与arrayFilters在选项 db.collection.findOneAndUpdate方法：

复制

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

该操作将更新grades单个文档的字段，并且在操作之后，集合将包含以下文档：

复制

MongoDB 中文手册

db.collection.findOneAndUpdate（）

定义¶

行为¶

单证相符¶

投影¶

分片集合¶

碎片键修改¶

交易¶

现有的收藏和交易¶

写的担忧和事务¶

例子¶

更新文件¶

排序和更新文档¶

投影返回的文档¶

更新文档有时间限制¶

使用Upsert更新文档¶

指定归类¶

阵列更新操作与arrayFilters¶

更新元素匹配arrayFilters条件¶

阵列更新操作与`arrayFilters`¶

更新元素匹配`arrayFilters`条件¶