db.collection.findAndModify()

On this page本页内容

Definition定义

db.collection.findAndModify(document)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. 本页记录了mongo shell方法，未提及MongoDB Node.js驱动程序（或任何其他驱动程序）方法。For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.有关相应的MongoDB驱动程序API，请参阅特定的MongoDB驱动程序文档。

Modifies and returns a single document. 修改并返回单个文档。By default, the returned document does not include the modifications made on the update. 默认情况下，返回的文档不包括对更新所做的修改。To return the document with the modifications made on the update, use the new option. 要返回包含更新时所做修改的文档，请使用new选项。The findAndModify() method is a shell helper around the findAndModify command.findAndModify()方法是findAndModify命令的shell助手。

The findAndModify() method has the following form:findAndModify()方法的形式如下：

db.collection.findAndModify({
    query: <document>,
    sort: <document>,
    remove: <boolean>,
    update: <document or aggregation pipeline>, // Changed in MongoDB 4.2
    new: <boolean>,
    fields: <document>,
    upsert: <boolean>,
    bypassDocumentValidation: <boolean>,
    writeConcern: <document>,
    collation: <document>,
    arrayFilters: [ <filterdocument1>, ... ]
});

The db.collection.findAndModify() method takes a document parameter with the following embedded document fields:db.collection.findAndModify()方法采用带有以下嵌入文档字段的文档参数：

Parameter参数Type类型Description描述
query document

Optional.可选。The selection criteria for the modification. 修改的选择标准。The query field employs the same query selectors as used in the db.collection.find() method. query字段使用的查询选择器与db.collection.find()方法中使用的相同。Although the query may match multiple documents, db.collection.findAndModify() will only select one document to modify.尽管查询可能匹配多个文档，但db.collection.findAndModify()只会选择一个文档进行修改。

If unspecified, defaults to an empty document.如果未指定，则默认为空文档。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the query argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果查询参数不是文档，则会出现操作错误。

sort

 document

Optional.可选。Determines which document the operation modifies if the query selects multiple documents. 确定如果查询选择多个文档，操作将修改哪个文档。db.collection.findAndModify() modifies the first document in the sort order specified by this argument.按照此参数指定的排序顺序修改第一个文档。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the sort argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果排序参数不是文档，则会出现操作错误。

In MongoDB, sorts are inherently stable, unless sorting on a field which contains duplicate values:在MongoDB中，排序本质上是稳定的，除非对包含重复值的字段进行排序：

  • a stable sort is one that returns the same sort order each time it is performed稳定排序是每次执行时返回相同排序顺序的排序
  • an unstable sort is one that may return a different sort order when performed multiple times不稳定排序是指在多次执行时可能返回不同排序顺序的排序

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

See Sort Stability for more information.有关更多信息，请参阅排序稳定性。

remove boolean Must specify either the remove or the update field. 必须指定remove或update字段。Removes the document specified in the query field. 删除query字段中指定的文档。Set this to true to remove the selected document . 将此设置为true可删除所选文档。The default is false.默认值为false。
update document or 或array

Must specify either the remove or the update field. 必须指定remove或update字段。Performs an update of the selected document.执行所选文档的更新。

new boolean Optional.可选。When true, returns the modified document rather than the original. 如果为true，则返回修改后的文档，而不是原始文档。The db.collection.findAndModify() method ignores the new option for remove operations. db.collection.findAndModify()方法忽略remove操作的new选项。The default is false.默认值为false。
fields document

Optional.可选。A subset of fields to return. 要返回的字段的子集。The fields document specifies an inclusion of a field with 1, as in: fields: { <field1>: 1, <field2>: 1, ... }.fields文档指定包含一个带有1的字段，如：fields: { <field1>: 1, <field2>: 1, ... }。

Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the fields argument is not a document.从MongoDB 4.2（以及4.0.12+、3.6.14+和3.4.23+）开始，如果fields参数不是文档，则会出现操作错误。

For more information on projection, see fields Projection.有关投影的详细信息，请参阅字段投影。

upsert boolean

Optional.可选。Used in conjunction with the update field.与update字段一起使用。

When true, findAndModify() either:如果为true，则findAndModify()可以：

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

To avoid multiple upserts, ensure that the query fields are uniquely indexed.要避免多个upsert，请确保query字段的索引是唯一的。

Defaults to false.

bypassDocumentValidation boolean

Optional.可选。Enables db.collection.findAndModify to bypass document validation during the operation. 启用db.collection.findAndModify以在操作期间绕过文档验证。This lets you update documents that do not meet the validation requirements.这允许您更新不符合验证要求的文档。

New in version 3.2.版本3.2中的新功能。

writeConcern document

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.要将写关注点用于事务，请参阅事务和写关注点。

New in version 3.2.版本3.2中的新功能。

maxTimeMS integer Optional.可选。Specifies a time limit in milliseconds for processing the operation.指定处理操作的时间限制（以毫秒为单位）。
collation document

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选项语法如下所示：

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

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

New in version 3.4.版本3.4中的新功能。

arrayFilters array

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.如果标识符未包含在更新文档中，则不能使用标识符的数组筛选器文档。

Note

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（可能多次），则不能为包含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。

Note

arrayFilters is not available for updates that use an aggregation pipeline.不适用于使用聚合管道的更新。

New in version 3.6.版本3.6中的新功能。

Return Data返回数据

For remove operations, if the query matches a document, findAndModify() returns the removed document. 对于删除操作，如果查询与文档匹配，findAndModify()将返回删除的文档。If the query does not match a document to remove, findAndModify() returns null.如果查询与要删除的文档不匹配，findAndModify()将返回null。

For update operations, findAndModify() returns one of the following:对于更新操作，findAndModify()返回以下内容之一：

Behavior行为

fields Projection预测

Language Consistency

Starting in MongoDB 4.4, as part of making find and findAndModify projection consistent with aggregation’s $project stage,从MongoDB 4.4开始，作为使find和findAndModify投影与聚合的$project阶段保持一致的一部分，

The fields option takes a document in the following form:fields选项采用以下格式的文档：

{ field1: <value>, field2: <value> ... }
ProjectionDescription描述
<field>: <1 or true> Specifies the inclusion of a field.指定字段的包含。
<field>: <0 or false> Specifies the exclusion of a field.指定字段的排除。
"<field>.$": <1 or true> With the use of the $ array projection operator, you can specify the projection to return the first element that match the query condition on the array field; e.g. "arrayField.$" : 1. 使用$数组投影运算符，可以指定投影以返回与数组字段上的查询条件匹配的第一个元素；例如，"arrayField.$" : 1。(Not available for views.)（不适用于视图。）
<field>: <array projection> Using the array projection operators $elemMatch, $slice, specifies the array element(s) to include, thereby excluding those elements that do not meet the expressions. 使用数组投影运算符$elemMatch，$slice，指定要包含的数组元素，从而排除那些不符合表达式的元素。(Not available for views.)（不适用于视图。）
<field>: <aggregation expression>

Specifies the value of the projected field.指定投影字段的值。

Starting in MongoDB 4.4, with the use of aggregation expressions and syntax, including the use of literals and aggregation variables, you can project new fields or project existing fields with new values.从MongoDB 4.4开始，通过使用聚合表达式和语法，包括使用文字和聚合变量，可以投影新字段或使用新值投影现有字段。For example,例如

  • If you specify a non-numeric, non-boolean literal (such as a literal string or an array or an operator expression) for the projection value, the field is projected with the new value; e.g.:如果为投影值指定非数字、非布尔文字（例如文字字符串、数组或运算符表达式），则会使用新值投影字段；如。：
    • { field: [ 1, 2, 3, "$someExistingField" ] }
    • { field: "New String Value" }
    • { field: { status: "Active", total: { $sum: "$existingArray" } } }
  • To project a literal value for a field, use the $literal aggregation expression; e.g.:要为字段投影文字值，请使用$literal聚合表达式；如。：
    • { field: { $literal: 5 } }
    • { field: { $literal: true } }
    • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }

In versions 4.2 and earlier, any specification value (with the exception of the previously unsupported document value) is treated as either true or false to indicate the inclusion or exclusion of the field.在版本4.2和更早版本中，任何规范值（以前不支持的文档值除外）都被视为true或false，以指示包含或排除该字段。

New in version 4.4.版本4.4中的新功能。

Embedded Field Specification嵌入式字段规范

For fields in an embedded documents, you can specify the field using either:对于嵌入文档中的字段，可以使用以下任一方法指定字段：

  • dot notation; e.g. 点符号；例如："field.nestedfield": <value>
  • nested form; e.g. 嵌套形式；如：{ field: { nestedfield: <value> } } (Starting in MongoDB 4.4从MongoDB 4.4开始)

_id Field Projection

The _id field is included in the returned documents by default unless you explicitly specify _id: 0 in the projection to suppress the field.默认情况下，_id字段包含在返回的文档中，除非在投影中明确指定_id:0以抑制该字段。

Inclusion or Exclusion包容还是排除

A projection cannot contain both include and exclude specifications, with the exception of the _id field:projection不能同时包含包含和排除规范，但_id字段除外：

  • In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.在显式包含字段的投影中，_id字段是唯一可以显式排除的字段。
  • In projections that explicitly excludes fields, the _id field is the only field that you can explicitly include; however, the _id field is included by default.在显式排除字段的投影中，_id字段是唯一可以显式包括的字段；但是，默认情况下会包含_id字段。

For more information on projection, see also:有关投影的更多信息，请参阅：

Upsert and Unique IndexUpsert和唯一索引

When findAndModify() includes the upsert: true option and the query field(s) is not uniquely indexed, the method could insert a document multiple times in certain circumstances.当findAndModify()包含upert:true选项且查询字段没有唯一索引时，该方法可能会在某些情况下多次插入文档。

In the following example, no document with the name Andy exists, and multiple clients issue the following command:在以下示例中，不存在名为Andy的文档，多个客户端发出以下命令：

db.people.findAndModify({
    query: { name: "Andy" },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

Then, if these clients’ findAndModify() methods finish the query phase before any command starts the modify phase, and there is no unique index on the name field, the commands may all perform an upsert, creating multiple duplicate documents.然后，如果这些客户机的findAndModify()方法在任何命令开始modify阶段之前完成了query阶段，并且name字段上没有唯一索引，那么这些命令可能都会执行upsert，从而创建多个重复文档。

To prevent the creation of multiple duplicate documents with the same name, create a unique index on the name field. 要防止创建多个同名重复文档，请在name字段上创建唯一索引。With this unique index in place, the multiple methods will exhibit one of the following behaviors:有了这个独特的索引，多种方法将表现出以下行为之一：

  • Exactly one findAndModify() successfully inserts a new document.只有一个findAndModify()成功插入了一个新文档。
  • Zero or more findAndModify() methods update the newly inserted document.零个或多个findAndModify()方法更新新插入的文档。
  • Zero or more findAndModify() methods fail when they attempt to insert documents with the same name. 零个或多个findAndModify()方法在尝试插入同名文档时失败。If the method fails due to the unique index constraint violation on the name field, you can retry the method. 如果该方法因名name字段上的唯一索引约束冲突而失败，则可以重试该方法。Absent a delete of the document, the retry should not fail.如果没有删除文档，重试不会失败。

Sharded Collections分片集合

When using findAndModify against a sharded collection, the query must contain an equality condition on shard key.对分片集合使用findAndModify时，查询必须在分片键上包含相等条件。

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，切分集合中的文档可能会缺少切分键字段。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). 要将缺少切分键的文档作为目标，可以将null相等匹配与另一个筛选条件结合使用（例如在_id字段上）。For example:例如：

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

Shard Key Modification分片密钥修改

Starting in MongoDB 4.2, you can update a document’s shard key value unless the shard key field is the immutable _id field. 从MongoDB 4.2开始，可以更新文档的shard key值，除非shard key字段是不可变的_id字段。Before MongoDB 4.2, a document’s shard key field value is immutable.在MongoDB 4.2之前，文档的shard key字段值是不可变的。

Warning警告

Starting in version 4.4, documents in sharded collections can be missing the shard key fields. 从4.4版开始，分片集合中的文档可能会缺少分片键字段。Take precaution to avoid accidentally removing the shard key when changing a document’s shard key value.采取预防措施，以避免在更改文档的shard key值时意外删除shard key。

To modify the existing shard key value with db.collection.findAndModify():要使用DBCollectionFindModify()修改现有分片键值，请执行以下操作：

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

Missing Shard Key缺少分片键

Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，切分集合中的文档可能会缺少切分键字段。To use db.collection.findAndModify() to set the document’s missing shard key:要使用db.collection.findAndModify()设置文档缺少的碎片键，请执行以下操作：

  • You must run on a mongos. 你必须在mongos上运行。Do not issue the operation directly on the shard.不要直接在碎片上发布操作。
  • You must run either in a transaction or as a retryable write if the new shard key value is not null.如果新的shard key值不为null，则必须在事务中或作为可重试写入运行。
  • You must include an equality filter on the full shard key.必须在完整分片键上包含相等筛选器。

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

See also:

Document Validation文件验证

The db.collection.findAndModify() method adds support for the bypassDocumentValidation option, which lets you bypass document validation when inserting or updating documents in a collection with validation rules.db.collection.findAndModify()方法增加了对bypassDocumentValidation选项的支持，该选项允许在使用验证规则插入或更新集合中的文档时绕过文档验证。

Comparisons with the update Method与update方法的比较

When updating a document, db.collection.findAndModify() and the update() method operate differently:更新文档时，db.collection.findAndModify()和update()方法的操作不同：

  • By default, both operations modify a single document. 默认情况下，这两个操作都会修改单个文档。However, the update() method with its multi option can modify more than one document.但是，update()方法及其multi选项可以修改多个文档。
  • If multiple documents match the update criteria, for db.collection.findAndModify(), you can specify a sort to provide some measure of control on which document to update.如果多个文档符合更新条件，对于db.collection.findAndModify()，可以指定一种sort，以提供对要更新的文档的某种控制措施。

    With the default behavior of the update() method, you cannot specify which single document to update when multiple documents match.使用update()方法的默认行为，当多个文档匹配时，不能指定要更新的单个文档。

  • By default, db.collection.findAndModify() returns the pre-modified version of the document. 默认情况下，db.collection.findAndModify()返回文档的预修改版本。To obtain the updated document, use the new option.要获取更新的文档，请使用new选项。

    The update() method returns a WriteResult object that contains the status of the operation. update()方法返回一个WriteResult对象，该对象包含操作的状态。To return the updated document, use the find() method. 要返回更新的文档，请使用find()方法。However, other updates may have modified the document between your update and the document retrieval. 但是，其他更新可能在更新和文档检索之间修改了文档。Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.此外，如果更新只修改了一个文档，但匹配了多个文档，则需要使用其他逻辑来标识更新后的文档。

When modifying a single document, both db.collection.findAndModify() and the update() method atomically update the document. 修改单个文档时，db.collection.findAndModify()和update()方法都会自动更新文档。See Atomicity and Transactions for more details about interactions and order of operations of these methods.有关这些方法的交互和操作顺序的更多详细信息，请参阅原子性和事务。

Transactions事务

db.collection.findAndModify() can be used inside multi-document transactions.可以在多文档事务中使用。

Important重要的

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

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

Upsert within Transactions在事务中插入

Starting in MongoDB 4.4 with feature compatibility version (fcv) "4.4", you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.从功能兼容版本（fcv）"4.4"的MongoDB 4.4开始，如果事务不是跨切分写入事务，则可以在多文档事务中创建集合和索引。

As such, for the feature compatibility version (fcv) is "4.4" or greater, db.collection.findAndModify() with upsert: true can be run against an existing collection or a non-existing collection. 因此，对于功能兼容性版本（fcv）为"4.4"或更高版本的情况，可以对现有集合或不存在的集合运行带有upsert:true的db.collection.findAndModify()。If run against a non-existing collection, the operation creates the collection.如果针对不存在的集合运行，该操作将创建该集合。

If the feature compatibility version (fcv) is "4.2" or less, the operation must be against an existing collection.如果功能兼容版本（fcv）为"4.2"或更低，则操作必须针对现有集合。

See also参阅

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.要将写关注点用于事务，请参阅事务和写关注点。

Examples示例

Update and Return更新并返回

The following method updates and returns an existing document in the people collection where the document matches the query criteria:以下方法更新并返回人员集合中与查询条件匹配的现有文档：

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

This method performs the following actions:此方法执行以下操作：

  1. The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.query会在people集合中找到一个文档，其中name字段的值为Tom，state字段的值为active，rating字段的值大于10。
  2. The sort orders the results of the query in ascending order. sort按升序排列查询结果。If multiple documents meet the query condition, the method will select for modification the first document as ordered by this sort.如果多张单据满足query条件，则该方法会选择按此sort排序的第一张单据进行修改。
  3. The update increments the value of the score field by 1.更新将score字段的值增加1。
  4. The method returns the original (i.e. pre-modification) document selected for this update:该方法返回为此更新选择的原始（即修改前）文档：

    {
  "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
  "name" : "Tom",
  "state" : "active",
  "rating" : 100,
  "score" : 5
}

    To return the modified document, add the new:true option to the method.要返回修改过的文档，请将new:true选项添加到方法中。

    If no document matched the query condition, the method returns null.如果没有与query条件匹配的文档，则该方法返回null。

Upsert

The following method includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:以下方法包括upsert:true选项，用于update操作，以更新匹配的文档，或者如果不存在匹配的文档，则创建新文档：

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

If the method finds a matching document, the method performs an update.如果该方法找到匹配的文档，则该方法将执行更新。

If the method does not find a matching document, the method creates a new document. 如果该方法没有找到匹配的文档，则该方法将创建一个新文档。Because the method included the sort option, it returns an empty document { } as the original (pre-modification) document:因为该方法包含排序选项，所以它返回一个空文档{ }，作为原始（修改前）文档：

{ }

If the method did not include a sort option, the method returns null.如果该方法不包含sort选项，则该方法返回null。

null

Return New Document退回新文件

The following method includes both the upsert: true option and the new:true option. 以下方法包括upsert:true选项和new:true选项。The method either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.该方法要么更新匹配文档并返回更新后的文档，要么在不存在匹配文档的情况下插入文档并在value字段中返回新插入的文档。

In the following example, no document in the people collection matches the query condition:在以下示例中，people集合中没有与查询条件匹配的文档：

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

The method returns the newly inserted document:该方法返回新插入的文档：

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Sort and Remove排序并删除

By including a sort specification on the rating field, the following example removes from the people collection a single document with the state value of active and the lowest rating among the matching documents:通过在rating字段中包含sort规范，以下示例将从people集合中删除state值active且rating最低的单个文档：

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

The method returns the deleted document:该方法返回已删除的文档：

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

Specify Collation指定排序规则

New in version 3.4.版本3.4中的新功能。

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集合包含以下文档：

{ _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.findAndModify({
    query: { category: "cafe", status: "a" },
    sort: { category: 1 },
    update: { $set: { status: "Updated" } },
    collation: { locale: "fr", strength: 1 }
});

The operation returns the following document:该操作将返回以下文档：

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

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

Note

arrayFilters is not available for updates that use an aggregation pipeline.不适用于使用聚合管道的更新。

New in version 3.6.版本3.6中的新功能。

Starting in MongoDB 3.6, when updating an array field, you can specify arrayFilters that determine which array elements to update.从MongoDB 3.6开始，在更新数组字段时，可以指定确定要更新哪些数组元素的arrayFilters。

Update Elements Match arrayFilters Criteria更新元素匹配arrayFilters条件

Note

arrayFilters is not available for updates that use an aggregation pipeline.arrayFilters不适用于使用聚合管道的更新。

Create a collection students with the following documents:创建一个包含以下文档的集合students：

db.students.insert([
   { "_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.findAndModify method:要修改grades数组中大于或等于100的所有元素，请在db.collection.findAndModify方法中使用筛选的位置运算符$[<identifier>]和arrayFilters选项：

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

The operation updates the grades field for 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更新文档数组的特定元素

Note

arrayFilters is not available for updates that use an aggregation pipeline.arrayFilters不适用于使用聚合管道的更新。

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

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

The following operation finds a document where the _id field equals 1 and uses the filtered positional operator $[<identifier>] with the arrayFilters to modify the mean for all elements in the grades array where the grade is greater than or equal to 85.以下操作将查找_id字段等于1的文档，并使用筛选后的位置运算符$[<identifier>]和arrayFilters来修改grades数组中等级大于或等于85的所有元素的平均值。

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

The operation updates the grades field for a single document, and after the operation, the collection has the following documents:该操作将更新单个文档的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 }
   ]
}

Use an Aggregation Pipeline for Updates使用聚合管道进行更新

Starting in MongoDB 4.2, db.collection.findAndModify() can accept an aggregation pipeline for the update. 从MongoDB 4.2开始，db.collection.findAndModify()可以接受更新的聚合管道。The pipeline can consist of the following stages:管道可包括以下阶段：

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).使用聚合管道可以实现更具表现力的update语句，例如基于当前字段值表达条件更新，或者使用另一个字段的值更新一个字段。

For example, create a collection students2 with the following documents:例如，使用以下文档创建students2集合：

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

The following operation finds a document where the _id field equals 1 and uses an aggregation pipeline to calculate a new field total from the grades field:以下操作将查找_id字段等于1的文档，并使用聚合管道从grades字段计算新字段grades：

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

Note

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

The operation returns the updated document:该操作将返回更新后的文档：

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

See also参阅

Linearizable Reads via findAndModify通过FindModify进行线性化读取