db.collection.updateOne()

在此页面上

定义

兼容性
语法
访问控制
行为
举例

定义

db.collection.updateOne(filter, update, options): 重要
mongosh 方法
本页介绍了 mongosh方法。这不是数据库命令或特定语言驱动程序（例如 Node.js）的文档。
有关数据库命令，请参阅 update 命令。
对于 MongoDB API 驱动程序，请参阅特定语言的MongoDB 驱动程序文档。
对于传统 mongo Shell 文档，请参阅相应 MongoDB Server 版本的文档：
mongo shell v4.4
根据筛选器更新集合内的单个文档。

兼容性

可以使用 db.collection.updateOne() 查找托管在以下环境中的部署：

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

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

语法

updateOne()方法采用以下语法：

db.collection.updateOne(
   <filter>,
   <update>,
   {
     upsert: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ],
     hint:  <document|string>,
     let: <document>
   }
)

参数

db.collection.updateOne()方法采用以下参数：

范围

类型

说明

筛选器

文档

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

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

更新

文档或管道

要应用的修改。可以是以下之一：


更新文档	只包含更新操作符表达式。有关详细信息，请参阅使用更新操作符表达式文档进行更新
聚合管道	仅包含以下聚合阶段： `$addFields` 及其别名 `$set` `$project` 及其别名 `$unset` `$replaceRoot` 及其别名 `$replaceWith`。有关更多信息，请参阅使用聚合管道更新。

要使用替换文档进行更新，请参阅 db.collection.replaceOne()。

upsert

布尔

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

如果没有文档与 filter 匹配，则创建一个新文档。有关详细信息，请参阅更新或插入行为。
更新与 filter 匹配的单份文档。

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

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

writeConcern

文档

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

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

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 。

hint

文档或字符串

可选。指定用于支持查询谓词的索引的文档或字符串。

该选项可以采用索引规范文档或索引名称字符串。

如果指定不存在的索引，则操作出错。

有关示例，请参阅为更新操作指定hint 。

let

文档

可选。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

注意

要使用变量筛选结果，您必须在 $expr 操作符中访问该变量。

有关使用let和变量的完整示例，请参阅使用 let 变量进行更新。

该方法返回包含以下内容的文档：

matchedCount 包含匹配文档的数量
modifiedCount 包含已修改文档的数量
upsertedId ，包含用于已更新或插入的文档的 _id
upsertedCount 包含更新或插入文档的数量
如果操作使用写关注来运行，则布尔值 acknowledged 为 true；如果已禁用写关注，则为 false

访问控制

在使用 authorization 运行的部署中，用户必须具有包含以下特权的访问权限：

update 针对指定集合的操作。
find 针对指定集合的操作。
insert 如果操作导致更新插入，则对指定收集执行操作。

内置角色readWrite提供所需的特权。

行为

更新单个文档

db.collection.updateOne()查找与筛选器匹配的第一个文档并应用指定的更新修改。

使用更新操作符表达式文档进行更新

对于更新规范， db.collection.updateOne()方法可接受仅包含更新操作符表达式的文档。

例如：

db.collection.updateOne(
   <query>,
   { $set: { status: "D" }, $inc: { quantity: 2 } },
   ...
)

使用聚合管道进行更新

db.collection.updateOne()方法可接受指定要执行的修改的聚合管道[ <stage1>, <stage2>, ... ] 。该管道可以由以下阶段组成：

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

例如：

db.collection.updateOne(
   <query>,
   [
      { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
      { $unset: [ "misc1", "misc2" ] }
   ]
   ...
)

注意

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

有关示例，请参阅使用聚合管道进行更新。

更新插入

如果upsert: true且没有文档与filter匹配，则db.collection.updateOne()将根据filter标准和update修改创建新文档。请参阅使用更新或插入进行更新。

如果在分片集合上指定upsert: true ，则必须在筛选器中包含完整的分片键。有关分片集合上的其他db.collection.updateOne()行为，请参阅分片集合。

固定大小集合

如果更新操作更改了文档大小，则操作将失败。

分片集合

`upsert` 分片集合

要在分片集合上使用db.collection.updateOne() ：

如果不指定 upsert: true，则必须在 _id 字段中包含精确匹配或定位单个分片（例如通过在过滤器中包含分片键）。
如果指定 upsert: true，则过滤器必须包含分片键。

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

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

分片键修改

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

警告

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

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

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

另请参阅分片集合上的upsert 。

缺少分片键

分片集合中的文档可能缺少分片键字段。要使用db.collection.updateOne()设置缺失的分片键，必须在mongos上运行。请勿直接对分片发出此操作。

此外，以下要求也适用：

任务	要求
若要设为 `null`	如果 `upsert: true`，则需使用针对完整分片键的相等筛选器。
要设置为非 `null` 值	必须在事务中或作为可重试写入执行。如果 `upsert: true`，则需使用针对完整分片键的相等筛选器。

提示

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

另请参阅：

可解释性

updateOne()与db.collection.explain()不兼容。

事务

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

重要

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

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

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

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

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

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

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

Oplog 条目

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

举例

使用更新操作符表达式进行更新

restaurant 集合包含以下文档：

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

以下操作更新单个文档，文档中的 name: "Central Perk Cafe" 带有 violations 字段：

try {
   db.restaurant.updateOne(
      { "name" : "Central Perk Cafe" },
      { $set: { "violations" : 3 } }
   );
} catch (e) {
   print(e);
}

该操作返回：

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

如果未找到匹配项，那么操作将返回：

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

如果未找到匹配项，设置 upsert: true 则会插入该文档。请参阅使用更新或插入进行更新

使用聚合管道进行更新

db.collection.updateOne()可以使用聚合管道进行更新。该管道可以由以下阶段组成：

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

示例 1

以下示例使用聚合分析管道使用文档中其他字段的值来修改字段。

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

db.students.insertMany( [
   { "_id" : 1, "student" : "Skye", "points" : 75, "commentsSemester1" : "great at math", "commentsSemester2" : "loses temper", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
   { "_id" : 2, "student" : "Elizabeth", "points" : 60, "commentsSemester1" : "well behaved", "commentsSemester2" : "needs improvement", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

假设希望像第二份文档一样，将第一份文档中的 commentsSemester1 和 commentsSemester2 字段聚集到一个 comments 字段中，而不单独使用这两个字段。以下更新操作使用聚合管道：

添加新的 comments 字段并设置 lastUpdate 字段。
删除集合中所有文档的 commentsSemester1 和 commentsSemester2 字段。

确保更新命令中的筛选器定针对唯一文档。以下代码中的字段 id 便是此类筛选器的示例：

db.students.updateOne(
   { _id: 1 },
   [
      { $set: { status: "Modified", comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } },
      { $unset: [ "commentsSemester1", "commentsSemester2" ] }
   ]
)

注意

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

第一个阶段：

$set 阶段：

创建一个新的数组字段 comments，其元素是 misc1 和 misc2 字段的当前内容，并且
将字段 lastUpdate 设置为聚合变量 NOW 的值。聚合变量 NOW 解析为当前的日期时间值，并在整个管道中保持不变。要访问聚合变量，在变量前加上双美元符号 $$ 并用引号引起来。

第二阶段

$unset 阶段删除 commentsSemester1 和 commentsSemester2 字段。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 2, "student" : "Elizabeth", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "well behaved", "needs improvement" ] }
{ _id: 1, student: 'Skye', points: 75, commentsSemester1: 'great at math', commentsSemester2: 'loses temper', lastUpdate: ISODate("2019-01-01T00:00:00.000Z") }

请注意，引入排序后，仅修改排序顺序中遇到的第一份文档，其余文档保持不变。

示例 2

聚合分析管道允许更新根据当前字段值执行条件更新以及使用当前字段值计算单独的字段值。

例如，使用以下文档创建 students3 集合：

db.students3.insertMany( [
   { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
   { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

第三个文档 _id: 3 缺少 average 和 grade 字段。使用聚合管道，可以根据计算出的平均成绩和字母等级来更新文档。

db.students3.updateOne(
   { _id: 3 },
   [
     { $set: { average: { $trunc: [  { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } },
     { $set: { grade: { $switch: {
                           branches: [
                               { case: { $gte: [ "$average", 90 ] }, then: "A" },
                               { case: { $gte: [ "$average", 80 ] }, then: "B" },
                               { case: { $gte: [ "$average", 70 ] }, then: "C" },
                               { case: { $gte: [ "$average", 60 ] }, then: "D" }
                           ],
                           default: "F"
     } } } }
   ]
)

注意

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

第一个阶段：

$set 阶段：

根据 tests 字段的平均值计算新字段 average。有关 $avg 聚合操作符的详细信息，请参阅 $avg，有关 $trunc 截断聚合操作符的详细信息，请参阅 $trunc。
将字段 lastUpdate 设置为聚合变量 NOW 的值。聚合变量 NOW 解析为当前的日期时间值，并在整个管道中保持不变。要访问聚合变量，在变量前加上双美元符号 $$ 并用引号引起来。

第二阶段

$set 阶段根据上一阶段计算的 average 字段计算新字段 grade。有关 $switch 聚合操作符的更多信息，请参阅 $switch。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" }

提示

另请参阅：

使用聚合管道进行更新。

使用更新或插入进行更新

restaurant 集合包含以下文档：

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : "0" }

以下操作尝试使用 name : "Pizza Rat's Pizzaria" 更新文档，同时 upsert: true：

try {
   db.restaurant.updateOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { $set: {"_id" : 4, "violations" : 7, "borough" : "Manhattan" } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

因为 upsert:true，所以该文档是基于 filter 和 update 标准 inserted 的。该操作返回：

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4,
   "upsertedCount": 1
}

该集合现在包含以下文档：

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 7 }

name 字段使用 filter 条件填充，而 update 操作符用于创建文档的其余部分。

以下操作会使用大于 10 的 violations 更新第一个文档：

try {
   db.restaurant.updateOne(
      { "violations" : { $gt: 10} },
      { $set: { "Closed" : true } },
      { upsert: true }
   );
} catch (e) {
   print(e);
}

该操作返回：

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea")
}

该集合现在包含以下文档：

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "grade" : 7 }
{ "_id" : ObjectId("56310c3c0c5cbb6031cafaea"), "Closed" : true }

由于没有文档与筛选器匹配，并且upsert为true ，因此updateOne()仅使用生成的_id和update条件插入该文档。

使用写关注更新

给定一个三节点副本集，以下操作指定 w 为 majority，指定 wtimeout 为 100：

try {
   db.restaurant.updateOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { $inc: { "violations" : 3}, $set: { "Closed" : true } },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

如果主节点和至少一个从节点在 100 毫秒内确认每个写入操作，则返回：

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

如果确认花费的时间超过wtimeout限制，则会引发以下异常：

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

下表解释了 errInfo.writeConcern.provenance 的可能值：

来源	说明
`clientSupplied`	应用程序中指定了写关注。
`customDefault`	写入关注源自自定义的默认值。请参阅 `setDefaultRWConcern`。
`getLastErrorDefaults`	写关注源自副本集的 `settings.getLastErrorDefaults` 字段。
`implicitDefault`	在没有所有其他写入关注规范的情况下，写入关注源自服务器。

指定排序规则。

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

集合 myColl 包含以下文档：

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

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

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

为数组更新操作指定 `arrayFilters`

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

更新元素匹配 `arrayFilters` 条件

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

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

要修改数组中大于或等于的所有元素，请在100 grades方法中使用筛选后的位置运算符$[<identifier>] 和arrayFilters db.collection.updateOne()选项：

db.students.updateOne(
   { 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 ] }

更新文档数组的特定元素

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

要修改grades数组中分数大于或等于85的所有元素的mean字段的值，请使用筛选后的位置运算符$[<identifier>]和 db.collection.updateOne() 中的arrayFilters 方法：

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

该操作更新单个文档的数组，操作后，该集合包含以下文档：

{
   "_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 }
   ]
}

为更新操作指定 `hint`

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

db.students.insertMany( [
   { "_id" : 1, "student" : "Richard", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 2, "student" : "Jane", "grade" : "A", "points" : 60,  "comments1" : "well behaved", "comments2" : "fantastic student" },
   { "_id" : 3, "student" : "Ronan", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 4, "student" : "Noah", "grade" : "D", "points" : 20,  "comments1" : "needs improvement", "comments2" : null },
   { "_id" : 5, "student" : "Adam", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 6, "student" : "Henry", "grade" : "A", "points" : 86,  "comments1" : "fantastic student", "comments2" : "well behaved" }
] )

在集合上创建以下索引：

db.students.createIndex( { grade: 1 } )
db.students.createIndex( { points: 1 } )

以下更新操作明确提示使用索引 { grade: 1 }：

注意

如果指定不存在的索引，则操作出错。

db.students.updateOne(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { hint: { grade: 1 } }
)

更新命令返回以下内容：

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

注意

即使有 3 个文档符合更新条件，updateOne 仅修改其查找到的第一个文档。因此，即使学生 Richard、Ronan 和 Adam 都符合条件，但只更新 Richard。

要查看使用的索引，请对操作运行 explain：

db.students.explain().update(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { multi: true, hint: { grade: 1 } }
)

用户角色和文档更新

从 MongoDB 7.0 开始，您可以使用新的 USER_ROLES 系统变量来返回用户角色。

本部分中的示例展示了包含医疗信息的集合中的字段更新。该示例从 USER_ROLES 系统变量中读取当前用户角色，并且仅在用户具有特定角色时才执行更新。

要使用系统变量，请将$$添加到变量名称的开头。将USER_ROLES系统变量指定为$$USER_ROLES。

该示例创建这些用户：

James 角色为 Billing。
Michelle 角色为 Provider。

执行以下步骤以创建角色、用户和集合：

创建角色

创建名为 Billing 和Provider 的角色，并赋予所需权限和资源。

运行：

db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )

创建用户

创建名为 James 和 Michelle 的用户，并赋予所需角色。

db.createUser( {
   user: "James",
   pwd: "js008",
   roles: [
      { role: "Billing", db: "test" }
   ]
} )
db.createUser( {
   user: "Michelle",
   pwd: "me009",
   roles: [
      { role: "Provider", db: "test" }
   ]
} )

创建集合

运行：

db.medical.insertMany( [
   {
      _id: 0,
      patientName: "Jack Jones",
      diagnosisCode: "CAS 17",
      creditCard: "1234-5678-9012-3456"
   },
   {
      _id: 1,
      patientName: "Mary Smith",
      diagnosisCode: "ACH 01",
      creditCard: "6541-7534-9637-3456"
   }
] )

以角色为 Provider 的 Michelle 身份登录，然后执行更新：

登录为 `Michelle`

运行：

db.auth( "Michelle", "me009" )

执行更新

运行：

// Attempt to update one document
db.medical.updateOne( {
   // User must have the Provider role to perform the update
   $expr: { $ne: [
      { $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 01"} }
)

前面的示例使用 $setIntersection 返回文档，其中，"Provider" 字符串与 $$USER_ROLES.role 中的用户角色之间的交集不为空。Michelle 的角色为 Provider，因此，将执行更新。

接下来，以不具有 Provider 角色的 James 身份登录，并尝试执行相同更新：

登录为 `James`

运行：

db.auth( "James", "js008" )

尝试执行更新

运行：

// Attempt to update one document
db.medical.updateOne( {
   // User must have the Provider role to perform the update
   $expr: { $ne: [
      { $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ] }, []
   ] } },
   // Update diagnosisCode
   { $set: { diagnosisCode: "ACH 01"} }
)

前面的示例没有更新任何文档。

提示

另请参阅：

要更新多个文档，请参阅 db.collection.updateMany()。

← db.collection.update()

db.collection.updateMany() →

定义

重要

mongosh 方法

兼容性

语法

参数

注意

注意

返回：

访问控制

行为

更新单个文档

使用更新操作符表达式文档进行更新

使用聚合管道进行更新

注意

更新插入

固定大小集合

分片集合

upsert 分片集合

分片键修改

警告

缺少分片键

提示

可解释性

事务

重要

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

提示

另请参阅：

写关注和事务

Oplog 条目

举例

使用更新操作符表达式进行更新

使用聚合管道进行更新

示例 1

注意

示例 2

注意

提示

另请参阅：

使用更新或插入进行更新

使用写关注更新

指定排序规则。

为数组更新操作指定 arrayFilters

更新元素匹配 arrayFilters 条件

更新文档数组的特定元素

为更新操作指定 hint

注意

注意

用户角色和文档更新

创建角色

创建用户

创建集合

登录为 Michelle

执行更新

登录为 James

尝试执行更新

提示

另请参阅：

`upsert` 分片集合

为数组更新操作指定 `arrayFilters`

更新元素匹配 `arrayFilters` 条件

为更新操作指定 `hint`

登录为 `Michelle`

登录为 `James`