Database Manual / Reference / mongosh Methods / Collections

db.collection.updateOne() (mongosh method方法)

Definition定义

db.collection.updateOne(filter, update, options)
Updates a single document within the collection based on the filter.根据筛选器更新集合中的单个文档。

Compatibility兼容性

This method is available in deployments hosted in the following environments:此方法在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

Note

This command is supported in all MongoDB Atlas clusters. 所有MongoDB Atlas集群都支持此命令。For information on Atlas support for all commands, see Unsupported Commands.有关Atlas支持所有命令的信息，请参阅不支持的命令。

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The updateOne() method has the following syntax:updateOne()方法具有以下语法：

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

Parameters参数

The db.collection.updateOne() method takes the following parameters:db.collection.updateOne()方法接受以下参数：

Parameter参数Type类型Description描述
filterdocument文档

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

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

updatedocument or pipeline文件或管道

The modifications to apply. Can be one of the following:要应用的修改。可以是以下之一：

Update document更新文档

Contains only update operator expressions.仅包含更新运算符表达式。

For more information, see Update with an Update Operator Expressions Document有关详细信息，请参阅使用更新运算符表达式文档进行更新

Aggregation pipeline聚合管道

Contains only the following aggregation stages:仅包含以下聚合阶段：

For more information, see Update with an Aggregation Pipeline.有关更多信息，请参阅使用聚合管道更新。

To update with a replacement document, see db.collection.replaceOne().要使用替换文档进行更新，请参阅db.collection.replaceOne()。

upsertboolean布尔值

Optional. 可选。When true, updateOne() either:当为true时，updateOne()会出现以下两种情况：

  • Creates a new document if no documents match the filter. For more details see upsert behavior.如果没有匹配filter的文档，则创建新文档。有关更多详细信息，请参阅upsert行为。
  • Updates a single document that matches the filter.更新与filter匹配的单个文档。

To avoid multiple upserts, ensure that the filter field(s) are uniquely indexed.为避免多个upsert，请确保对filter字段进行唯一索引。

Defaults to false, which does not insert a new document when no match is found.默认为false，当未找到匹配项时，不会插入新文档。

writeConcerndocument文档

Optional. 可选。A document expressing the write concern. Omit to use the default write concern.表达写入关注的文件。省略使用默认写入关注。

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.如果在事务中运行，则不要显式设置操作的写入关注。要对事务使用写关注，请参阅事务和写入关注。

collationdocument文档

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: {
   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. For descriptions of the fields, see Collation Document.指定排序规则时，locale字段是必填的；所有其他排序字段都是可选的。有关字段的描述，请参阅排序规则文档。

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.不能为操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果使用排序执行查找，则不能对查找使用一个排序规则，对排序使用另一个。

arrayFiltersarray数组

Optional. 可选。An array of filter documents that determine which array elements to modify for an update operation on an array field.一组筛选文档，用于确定在数组字段上进行更新操作时要修改哪些数组元素。

In the update document, use the $[<identifier>] filtered positional operator to define an identifier, which you then reference in the array filter documents. 在更新文档中，使用$[<identifier>]筛选位置运算符定义一个标识符，然后在数组筛选文档中引用该标识符。You cannot have an array filter document for an identifier if the identifier is not included in the update document.如果标识符未包含在更新文档中，则无法为标识符创建数组筛选器文档。

The <identifier> must begin with a lowercase letter and contain only alphanumeric characters.<identifier>必须以小写字母开头，并且只能包含字母数字字符。

You can include the same identifier multiple times in the update document; however, for each distinct identifier ($[identifier]) in the update document, you must specify exactly one corresponding array filter document. 您可以在更新文档中多次包含相同的标识符；但是，对于更新文档中的每个不同标识符（$[identifier]），您必须指定一个相应的数组筛选器文档。That is, you cannot specify multiple array filter documents for the same identifier. For example, if the update statement includes the identifier x (possibly multiple times), you cannot specify the following for arrayFilters that includes 2 separate filter documents for x:也就是说，不能为同一标识符指定多个数组筛选器文档。例如，如果更新语句包含标识符x（可能多次），则不能为包含2个单独的x筛选文档的arrayFilters指定以下内容：

// INVALID

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

However, you can specify compound conditions on the same identifier in a single filter document, such as in the following examples:但是，您可以在单个筛选器文档中为同一标识符指定复合条件，例如以下示例：

// 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 } }
]

For examples, see Specify arrayFilters for an Array Update Operations.有关示例，请参阅为数组更新操作指定arrayFilters。

hintDocument or string文档或字符串

Optional. 可选。A document or string that specifies the index to use to support the query predicate.指定用于支持查询谓词的索引的文档或字符串。

The option can take an index specification document or the index name string.该选项可以采用索引规范文档或索引名称字符串。

If you specify an index that does not exist, the operation errors.如果指定的索引不存在，则操作会出错。

For an example, see Specify hint for Update Operations.例如，请参阅指定更新操作的hint。

letDocument文档

Optional.可选。

Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text.指定一个包含变量列表的文档。这允许您通过将变量与查询文本分离来提高命令的可读性。

The document syntax is:文档语法为：

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

The variable is set to the value returned by the expression, and cannot be changed afterwards.变量设置为表达式返回的值，之后不能更改。

To access the value of a variable in the command, use the double dollar sign prefix ($$) together with your variable name in the form $$<variable_name>. For example: $$targetTotal.要在命令中访问变量的值，请使用双美元符号前缀（$$）和变量名，格式为$$<variable_name>。例如：$$targetTotal。

To use a variable to filter results, you must access the variable within the $expr operator.要使用变量筛选结果，您必须在$expr运算符中访问该变量。

For a complete example using let and variables, see Update with let Variables.有关使用let和变量的完整示例，请参阅使用let变量更新。

sortDocument文档

Optional.可选。

Determines which document the operation updates if the query selects multiple documents. updateOne updates the first document in the sort order specified by this argument.确定如果查询选择多个文档，则操作将更新哪个文档。updateOne按照此参数指定的排序顺序更新第一个文档。

If the sort argument is not a document, the operation errors.如果排序参数不是文档，则操作会出错。

MongoDB does not store documents in a collection in a particular order. When sorting on a field which contains duplicate values, documents containing those values may be returned in any order.MongoDB不会以特定顺序将文档存储在集合中。在对包含重复值的字段进行排序时，包含这些值的文档可以按任何顺序返回。

The $sort operation is not a "stable sort," which means that documents with equivalent sort keys are not guaranteed to remain in the same relative order in the output as they were in the input.$sort操作不是“稳定排序”，这意味着具有等效排序键的文档不能保证在输出中保持与输入中相同的相对顺序。

If the field specified in the sort criteria does not exist in two documents, then the value on which they are sorted is the same. The two documents may be returned in any order.如果排序条件中指定的字段在两个文档中不存在，则对它们进行排序的值是相同的。这两份文件可以按任何顺序退回。

If consistent sort order is desired, include at least one field in your sort that contains unique values. The easiest way to guarantee this is to include the _id field in your sort query.如果需要一致的排序顺序，请在排序中至少包含一个包含唯一值的字段。保证这一点的最简单方法是在排序查询中包含_id字段。

See Sort Consistency for more information.有关详细信息，请参阅排序一致性。

New in version 8.0.在版本8.0中新增。

maxTimeMSinteger整数

Optional. 可选。Specifies the time limit in milliseconds for the update operation to run before timing out.指定在超时之前运行更新操作的时间限制（以毫秒为单位）。

bypassDocumentValidationboolean布尔值

Optional. 可选。Enables insert to bypass schema validation during the operation. This lets you insert documents that do not meet the validation requirements.启用insert以在操作期间绕过架构验证。这允许您插入不符合验证要求的文档。

Returns值

The method returns a document that contains:该方法返回一个文档，其中包含：

  • matchedCount containing the number of matched documents包含匹配文档的数量
  • modifiedCount containing the number of modified documents包含已修改文档的数量
  • upsertedId containing the _id for the upserted document包含已更新文档的_id
  • upsertedCount containing the number of upserted documents包含被打乱的文档数量
  • A boolean acknowledged as true if the operation ran with write concern or false if write concern was disabled如果操作在写入关注下运行，则布尔值acknowledged为true，如果写入关注被禁用，则确认为false

Access Control访问控制

On deployments running with authorization, the user must have access that includes the following privileges:在authorization（授权）运行的部署中，用户必须具有包括以下权限的访问权限：

  • update action on the specified collection(s).指定集合上的update操作。
  • find action on the specified collection(s).指定集合上的find操作。
  • insert action on the specified collection(s) if the operation results in an upsert.如果操作导致upsert，请在指定的集合上insert操作。

The built-in role readWrite provides the required privileges.内置角色readWrite提供了所需的权限。

Behavior行为

Updates a Single Document更新单个文档

db.collection.updateOne() finds the first document that matches the filter and applies the specified update modifications.查找与filter匹配的第一个文档并应用指定的更新修改。

Update with an Update Operator Expressions Document使用更新运算符表达式文档进行更新

For the update specifications, the db.collection.updateOne() method can accept a document that only contains update operator expressions.对于更新规范，db.collection.updateOne()方法可以接受仅包含更新运算符表达式的文档。

For example:例如：

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

Update with an Aggregation Pipeline使用聚合管道进行更新

The db.collection.updateOne() method can accept an aggregation pipeline [ <stage1>, <stage2>, ... ] that specifies the modifications to perform. The pipeline can consist of the following stages:db.collection.updateOne()方法可以接受指定要执行的修改的聚合管道[ <stage1>, <stage2>, ... ]。该管道可以由以下阶段组成：

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).使用聚合管道允许更具表现力的更新语句，例如基于当前字段值表示条件更新，或使用另一个字段的值更新一个字段。

For example:例如：

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

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.管道中使用的$set和$unset分别指聚合阶段$set和$sunset，而不是更新运算符$set和$iunset。

For examples, see Update with Aggregation Pipeline.有关示例，请参阅使用聚合管道进行更新。

Upsert

Capped Collection固定集合

If an update operation changes the document size, the operation will fail.如果更新操作更改了文档大小，则操作将失败。

Sharded Collections分片化集合

upsert on a Sharded Collection分片系列上的upsert

To use db.collection.updateOne() on a sharded collection:要在分片集合上使用db.collection.updateOne()，请执行以下操作：

  • Starting in MongoDB 7.1, if you specify upsert: true on a sharded collection, you do not need to include the full shard key in the filter.从MongoDB 7.1开始，如果你在分片集合上指定upsert: true，你就不需要在filter中包含完整的分片键。
  • If you don't specify upsert: true, you must include an exact match on the _id field or target a single shard (such as by including the shard key in the filter).如果不指定upsert: true，则必须在_id字段中包含完全匹配的项，或者以单个分片为目标（例如在筛选器中包含分片键）。

However, documents in a sharded collection can be missing the shard key fields. 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). For example:但是，分片集合中的文档可能会缺少分片键字段。要针对缺少分片键的文档，您可以将空相等匹配与另一个筛选条件结合使用（例如在_id字段上）。例如：

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

Shard Key Modification分片键修改

You can update a document's shard key value unless the shard key field is the immutable _id field.您可以更新文档的分片键值，除非分片键字段是不可变的_id字段。

Warning

Documents in sharded collections can be missing the shard key fields. 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.updateOne():要使用db.collection.updateOne()修改现有的分片键值，请执行以下操作：

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

See also upsert on a Sharded Collection.另请参阅分片系列的upsert。

Missing Shard Key缺少分片键

  • Starting in version 7.1, you do not need to provide the shard key or _id field in the query specification.从7.1版本开始，您不需要在查询规范中提供分片键或_id字段。

  • Documents in a sharded collection can be missing the shard key fields. To use db.collection.updateOne() to set a missing shard key, you must run on a mongos. 分片集合中的文档可能缺少分片键字段。要使用dbcollectionupdateOne()设置丢失的分片键，您必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在分片上执行操作。

    In addition, the following requirements also apply:此外，以下要求也适用：

    Task任务Requirements需求
    To set to null若要设置为nullRequires equality filter on the full shard key if upsert: true.需要对整个分片键进行相等筛选，前提是upstart为true。
    To set to a non-null value设置为非null值

    Must be performed either inside a transaction or as a retryable write.必须在事务内部或作为可重试写入执行。

    Requires equality filter on the full shard key if upsert: true.如果upsert: true，则需要对完整分片键进行相等筛选器。

    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.由于缺少的键值是作为空相等匹配的一部分返回的，为了避免更新null值键值，请酌情包含其他查询条件（例如在_id字段上）。

See also:另请参阅：

Explainability可解释性

updateOne() is not compatible with db.collection.explain().updateOne()与db.collection.explain()不兼容。

Transactions事务

db.collection.updateOne() can be used inside distributed transactions.db.collection.updateOne()可以在分布式事务中使用。

Important

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed 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 distributed transactions.也就是说，对于许多场景，适当地对数据进行建模将最大限度地减少对分布式事务的需求。

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

Upsert within Transactions事务中的upsert

You can create collections and indexes inside a distributed transaction if the transaction is not a cross-shard write transaction.如果分布式事务不是跨分片写入事务，则可以在该事务内创建集合和索引。

db.collection.updateOne() with upsert: true can be run on an existing collection or a non-existing collection. If run on a non-existing collection, the operation creates the collection.db.collection.updateOne()和upsert: true可以在现有集合或不存在的集合上运行。如果在不存在的集合上运行，则该操作将创建该集合。

Tip

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.如果在事务中运行，则不要显式设置操作的写入关注。要对事务使用写关注，请参阅事务和写关注。

Oplog Entries操作日志条目

If a db.collection.updateOne() operation successfully updates a document, the operation adds an entry on the oplog (operations log). 如果db.collection.updateOne()操作成功更新了文档，则该操作会在oplog（操作日志）上添加一个条目。If the operation fails or does not find a document to update, the operation does not add an entry on the oplog.如果操作失败或找不到要更新的文档，则操作不会在oplog上添加条目。

Examples示例

Update using Update Operator Expressions使用更新运算符表达式进行更新

The restaurant collection contains the following documents:restaurant集合包含以下文件：

db.restaurant.insertMany( [
   { _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 }
] )

The following operation updates a single document where name: "Central Perk Cafe" with the violations field:以下操作将用violations（违规）字段更新为name: "Central Perk Cafe"的单个文档：

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

The operation returns:操作返回：

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

If no matches were found, the operation instead returns:如果没有找到匹配项，则操作将返回：

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

Setting upsert: true would insert the document if no match was found. See Update with Upsert如果未找到匹配项，设置upsert: true将插入文档。请参阅使用Upsert更新

Update with Aggregation Pipeline使用聚合管道进行更新

The db.collection.updateOne() can use an aggregation pipeline for the update. The pipeline can consist of the following stages:db.collection.updateOne()可以使用聚合管道进行更新。管道可包括以下阶段：

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).使用聚合管道允许更具表现力的更新语句，例如基于当前字段值表示条件更新，或使用另一个字段的值更新一个字段。

Example 1示例1

The following examples uses the aggregation pipeline to modify a field using the values of the other fields in the document.以下示例使用聚合管道使用文档中其他字段的值修改字段。

Create a students collection with the following documents:使用以下文档创建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") }
] )

Assume that instead of separate commentsSemester1 and commentsSemester2 fields in the first document, you want to gather these into a comments field, like the second document. The following update operation uses an aggregation pipeline to:假设您不想在第一个文档中单独设置commentsSemester1和commentsSemester2字段，而是希望将它们集合到一个注释字段中，就像第二个文档一样。以下更新操作使用聚合管道来：

  • add the new comments field and set the lastUpdate field.添加新的comments字段并设置lastUpdate字段。
  • remove the commentsSemester1 and commentsSemester2 fields for all documents in the collection.删除集合中所有文档的commentsSemester1和commentsSemester2字段。

Make sure that the filter in the update command targets a unique document. The field id in the code below is an example of such a filter:确保update命令中的筛选器针对唯一的文档。下面代码中的字段id就是这样一个筛选器的示例：

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

Note

The $set and $unset used in the pipeline refers to the aggregation stages $set and $unset respectively, and not the update operators $set and $unset.管道中使用的$set和$unset分别指聚合阶段$set和$sunset，而不是更新运算符$set和$iunset。

First Stage第一阶段

The $set stage:$设置阶段：

  • creates a new array field comments whose elements are the current content of the misc1 and misc2 fields and创建一个新的数组字段注释，其元素是misc1和misc2字段的当前内容，以及
  • sets the field lastUpdate to the value of the aggregation variable NOW. 将字段lastUpdate设置为聚合变量NOW的值。The aggregation variable NOW resolves to the current datetime value and remains the same throughout the pipeline. 聚合变量NOW解析为当前日期时间值，并在整个管道中保持不变。To access aggregation variables, prefix the variable with double dollar signs $$ and enclose in quotes.要访问聚合变量，请在变量前添加双美元符号$$并括在引号中。
Second Stage第二阶段
The $unset stage removes the commentsSemester1 and commentsSemester2 fields.$unset阶段删除commentsSemester1和commentsSemester2字段。

After the command, the collection contains the following documents:命令后，集合包含以下文档：

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

Note that after introducing a sort, only the first document encountered in the sort order is modified and the remaining documents are left untouched.请注意，在引入排序后，只有排序顺序中遇到的第一个文档会被修改，其余文档则保持不变。

Example 2

The aggregation pipeline allows the update to perform conditional updates based on the current field values as well as use current field values to calculate a separate field value.聚合管道允许更新基于当前字段值执行条件更新，并使用当前字段值计算单独的字段值。

For example, create a students3 collection with the following documents:例如，使用以下文档创建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") }
] )

The third document _id: 3 is missing the average and grade fields. Using an aggregation pipeline, you can update the document with the calculated grade average and letter grade.第三个文档document_id:3缺少平均值和成绩字段。使用聚合管道，您可以使用计算出的平均成绩和字母成绩更新文档。

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"
     } } } }
   ]
)

Note

The $set used in the pipeline refers to the aggregation stage $set, and not the update operators $set.管道中使用的$set是指聚合阶段$set，而不是更新运算符$set。

First Stage第一阶段

The $set stage:$set阶段：

  • calculates a new field average based on the average of the tests field. 基于tests字段的平均值计算新的字段average。See $avg for more information on the $avg aggregation operator and $trunc for more information on the $trunc truncate aggregation operator.有关$avg聚合运算符的更多信息，请参阅$avg；有关$trunc截断聚合运算符的详细信息，请参阅$trunc。
  • sets the field lastUpdate to the value of the aggregation variable NOW. 将字段lastUpdate设置为聚合变量NOW的值。The aggregation variable NOW resolves to the current datetime value and remains the same throughout the pipeline. 聚合变量NOW解析为当前日期时间值，并在整个管道中保持不变。To access aggregation variables, prefix the variable with double dollar signs $$ and enclose in quotes.要访问聚合变量，请在变量前添加双美元符号$$并括在引号中。
Second Stage第二阶段
The $set stage calculates a new field grade based on the average field calculated in the previous stage. $set阶段根据前一阶段计算的average字段计算新的字段grade。See $switch for more information on the $switch aggregation operator.有关$switch聚合运算符的更多信息，请参阅$switch。

After the command, the collection contains the following documents:命令后，集合包含以下文档：

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

Tip

Updates with Aggregation Pipeline聚合管道的更新

Update with Upsert更新Upert

The restaurant collection contains the following documents:restaurant集合包含以下文件：

db.restaurant.insertMany( [
   { _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" }
] )

The following operation attempts to update the document with name : "Pizza Rat's Pizzaria", while upsert: true :以下操作尝试更新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);
}

Since upsert:true the document is inserted based on the filter and update criteria. The operation returns:由于upsert:true，文档将根据filter和update条件插入。操作返回：

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

The collection now contains the following documents:该集合现在包含以下文档：

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

The name field was filled in using the filter criteria, while the update operators were used to create the rest of the document.name字段是使用filter条件填写的，而update运算符用于创建文档的其余部分。

The following operation updates the first document with violations that are greater than 10:以下操作将使用大于10的violations更新第一个文档：

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

The operation returns:操作返回：

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

The collection now contains the following documents:该集合现在包含以下文档：

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

Since no documents matched the filter, and upsert was true, updateOne() inserted the document with a generated _id and the update criteria only.由于没有文档与筛选器匹配，并且upsert为true，updateOne()只插入了生成的_id和update条件的文档。

Update with Write Concern写入关注更新

Given a three member replica set, the following operation specifies a w of majority, wtimeout of 100:给定一个由三个成员组成的副本集，以下操作指定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);
}

If the primary and at least one secondary acknowledge each write operation within 100 milliseconds, it returns:如果主服务器和至少一个辅助服务器在100毫秒内确认每个写入操作，则返回：

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

If the acknowledgment takes longer than the wtimeout limit, the following exception is thrown:如果确认时间超过wtimeout限制，则抛出以下异常：

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

The following table explains the possible values of errInfo.writeConcern.provenance:下表解释了errInfo.writeConcern.provenance的可能值：

Provenance来源Description描述
clientSuppliedThe write concern was specified in the application.应用程序中指定了写入关注。
customDefaultThe write concern originated from a custom defined default value. See setDefaultRWConcern.写入关注源于自定义的默认值。请参阅setDefaultRWConcern。
getLastErrorDefaultsThe write concern originated from the replica set's settings.getLastErrorDefaults field.写入关注源于副本集的settings.getLastErrorDefaults字段。
implicitDefaultThe write concern originated from the server in absence of all other write concern specifications.在没有所有其他写入关注规范的情况下，写入关注源自服务器。

Update with Sort使用排序更新

New in version 8.0.在版本8.0中新增。

The following example deactivates the lowest rated active user:以下示例停用评级最低的活动用户：

db.people.updateOne(
   { state: "active" },
   { $set: { state: "inactive" } },
   { sort: { rating: 1 } }
)

Specify Collation指定排序规则

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

A collection myColl has 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.updateOne(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   { collation: { locale: "fr", strength: 1 } }
);

Specify arrayFilters for an Array Update Operations为数组更新操作指定arrayFilters

When updating an array field, you can specify arrayFilters that determine which array elements to update.更新数组字段时，可以指定arrayFilters来确定要更新的数组元素。

Update Elements Match arrayFilters Criteria更新元素arrayFilters筛选条件

Create a collection students with the following documents:使用以下文档创建students集合：

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

To modify all elements that are greater than or equal to 100 in the grades array, use the filtered positional operator $[<identifier>] with the arrayFilters option in the db.collection.updateOne() method:要修改grades数组中大于或等于100的所有元素，请在db.collection.updateOne()方法中使用带arrayFilters选项的筛选位置运算符$[<identifier>]：

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

The operation updates the grades field of a single document, and after the operation, the collection has the following documents:该操作更新单个文档的grades字段，操作后，集合包含以下文档：

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

Update Specific Elements of an Array of Documents更新文档数组的特定元素

Create a collection students2 with the following documents:使用以下文档创建集合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 }
      ]
   }
] )

To modify the value of the mean field for all elements in the grades array where the grade is greater than or equal to 85, use the filtered positional operator $[<identifier>] with the arrayFilters in the db.collection.updateOne() method:要修改grades数组中等级大于或等于85的所有元素的mean字段的值，请在dbcollectionupdateOne()方法中使用带arrayFilters的筛选位置运算符$[<identifier>]：

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

The operation updates the array of a single document, and after the operation, the collection has the following documents:该操作更新单个文档的数组，操作后，集合包含以下文档：

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

Specify hint for Update Operations指定更新操作的hint

Create a sample students collection with the following documents:使用以下文档创建示例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" }
] )

Create the following indexes on the collection:在集合上创建以下索引：

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

The following update operation explicitly hints to use the index { grade: 1 }:以下更新操作明确提示使用索引{ grade: 1 }：

Note

If you specify an index that does not exist, the operation errors.如果指定的索引不存在，则操作会出错。

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

The update command returns the following:更新命令返回以下内容：

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

Note

Even though 3 documents match the criteria of the update, updateOne only modifies the first document it finds. Therefore, even though the students Richard, Ronan, and Adam all meet the criteria, only Richard will be updated.即使有3个文档符合更新的条件，updateOne也只会修改它找到的第一个文档。因此，即使学生Richard、Ronan和Adam都符合标准，也只有Richard会被更新。

To see the index used, run explain on the operation:要查看使用的索引，请在操作上运行explain：

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

Write Concern Errors in Sharded Clusters分片集群中的写入关注错误

Changed in version 8.1.2.在版本8.1.2中的更改。

When db.collection.updateOne() executes on mongos in a sharded cluster, a writeConcernError is always reported in the response, even when one or more other errors occur. 当db.collection.updateOne()在分片集群中的mongos上执行时，即使出现一个或多个其他错误，也总是在响应中报告writeConcernError。In previous releases, other errors sometimes caused db.collection.updateOne() to not report write concern errors.在以前的版本中，其他错误有时会导致db.collection.updateOne()不报告写入关注错误。

For example, if a document fails validation, triggering a DocumentValidationFailed error, and a write concern error also occurs, both the DocumentValidationFailed error and the writeConcernError are returned in the top-level field of the response.例如，如果文档验证失败，触发DocumentValidationFailed错误，并且还发生写入关注错误，则DocumentValidationFailure错误和writeConcernError都会在响应的顶级字段中返回。

User Roles and Document Updates用户角色和文档更新

Starting in MongoDB 7.0, you can use the new USER_ROLES system variable to return user roles.从MongoDB 7.0开始，您可以使用新的USER_ROLES系统变量返回用户角色。

The example in this section shows updates to fields in a collection containing medical information. The example reads the current user roles from the USER_ROLES system variable and only performs the updates if the user has a specific role.本节中的示例显示了包含医疗信息的集合中字段的更新。该示例从USER_ROLES系统变量读取当前用户角色，并且仅在用户具有特定角色时执行更新。

To use a system variable, add $$ to the start of the variable name. Specify the USER_ROLES system variable as $$USER_ROLES.要使用系统变量，请在变量名的开头添加$$。将USER_ROLES系统变量指定为$$USER_ROLES。

The example creates these users:该示例创建了以下用户：

  • James with a Billing role.具有Billing角色
  • Michelle with a Provider role.具有Provider角色

Perform the following steps to create the roles, users, and collection:执行以下步骤以创建角色、用户和集合：

1

Create the roles创建角色

Create roles named Billing and Provider with the required privileges and resources.创建具有所需权限和资源的名为Billing和Provider的角色。

Run:运行：

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: [ ] } )
2

Create the users创建用户

Create users named James and Michelle with the required 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" }
   ]
} )
3

Create the collection创建集合

Run:运行：

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"
   }
] )

Log in as as Michelle, who has the Provider role, and perform an update:以Michelle（具有Provider角色）的身份登录，并执行更新：

1

Log in as Michelle以Michelle的身份登录

Run:运行：

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

Perform update执行更新

Run:运行：

// 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"} }
)

The previous example uses $setIntersection to return documents where the intersection between the "Provider" string and the user roles from $$USER_ROLES.role is not empty. 前面的示例使用$setIntersection返回文档，其中"Provider"字符串与$$USER_ROLES.role中的用户角色之间的交集不为空。Michelle has the Provider role, so the update is performed.Michelle具有Provider角色，因此执行更新。

Next, log in as as James, who does not have the Provider role, and attempt to perform the same update:接下来，以没有Provider角色的James身份登录，并尝试执行相同的更新：

1

Log in as James

Run:运行：

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

Attempt to perform update尝试执行更新

Run:运行：

// 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"} }
)

The previous example does not update any documents.前面的示例不会更新任何文档。

Tip

To update multiple documents, see db.collection.updateMany().要更新多个文档，请参阅db.collection.updateMany()。