On this page本页内容
db.collection.findOneAndUpdate( filter, update, options ) This is a mongosh method. This is not the documentation for Node.js or other programming language specific driver methods.
In most cases, mongosh methods work the same way as the legacy mongo shell methods. However, some legacy methods are unavailable in mongosh.
For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:
For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
Updates a single document based on the 根据filter and sort criteria.filter和sort条件更新单个文档。
The findOneAndUpdate() method has the following form: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>, ... ]
}
)
The findOneAndUpdate() method takes the following parameters:findOneAndUpdate()方法采用以下参数：
filter | document |
|
update | document or array |
|
projection | document |
|
sort | document |
|
maxTimeMS | number | |
upsert | boolean |
|
returnNewDocument | boolean |
|
collation | document |
collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}
|
arrayFilters | array |
// 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 } } ]
|
returnNewDocument: true, the updated document.eturnNewDocument:true，则返回更新的文档。 |
db.collection.findOneAndUpdate() updates the first matching document in the collection that matches the 更新集合中与filter. filter匹配的第一个匹配文档。If no document matches the 如果没有与filter, no document is updated.filter匹配的文档，则不会更新任何文档。
The sort parameter can be used to influence which document is updated.sort参数可用于影响更新哪个文档。
Starting in MongoDB 4.4, as part of making 从MongoDB 4.4开始，作为使find() and findAndModify() projection consistent with aggregation's $project stage,find()和findAndModify()投影与聚合的$project阶段一致的一部分，
find() and findAndModify() projection can accept aggregation expressions and syntax.find()和findAndModify()投影可以接受聚合表达式和语法。The projection parameter takes a document in the following form:projection参数采用以下形式的文档：
{ field1 : <value>, field2 : <value> ... }
| Projection | |
|---|---|
<field>: <1 or true> | true. true。 |
<field>: <0 or false> | |
"<field>.$": <1 or true> | $ 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。true. true。 |
<field>: <array projection> | $elemMatch, $slice, specifies the array element(s) to include, thereby excluding those elements that do not meet the expressions.$elemMatch、$slice指定要包含的数组元素，从而排除那些不符合表达式的元素。 |
<field>: <aggregation expression> |
|
For fields in an embedded documents, you can specify the field using either:对于嵌入文档中的字段，可以使用以下任一方法指定字段：
"field.nestedfield": <value>{ field: { nestedfield: <value> } } (Starting in MongoDB 4.4)_idThe 默认情况下，_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以抑制该字段。
A projection cannot contain both include and exclude specifications, with the exception of the _id field:projection不能同时包含包含和排除规范，但_id字段除外：
_id field is the only field that you can explicitly exclude._id字段是唯一可以显式排除的字段。_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:有关投影的更多信息，请参阅：
To use 要在分片集合上使用db.collection.findOneAndUpdate() on a sharded collection, the query filter must include an equality condition on the shard key.db.collection.findOneAndUpdate()，查询筛选器必须在分片键上包含相等条件。
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
Starting in MongoDB 4.2, you can update a document's shard key value unless the shard key field is the immutable 从MongoDB 4.2开始，您可以更新文档的分片键值，除非分片键值字段是不可变的_id field. _id字段。In MongoDB 4.2 and earlier, a document's shard key field value is immutable.在MongoDB 4.2及更早版本中，文档的shard键字段值是不可变的。
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.在更改文档的分片键值时，请采取预防措施，以避免意外删除分片键。
To modify the existing shard key value with 要使用db.collection.findOneAndUpdate():db.collection.findOneAndUpdate()修改现有的分片键值：
mongos. mongos上。Starting in version 4.4, documents in a sharded collection can be missing the shard key fields. 从4.4版开始，分片集合中的文档可能会缺少分片键字段。To use 要使用db.collection.findOneAndUpdate() to set the document's missing shard key,db.collection.findOneAndUpdate()设置文档缺少的分片键，
mongos. mongos上。null.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相等匹配的一部分返回的，为了避免更新null值键，请酌情包括其他查询条件（例如在_id字段上）。
See also:另请参见：
db.collection.findOneAndUpdate() can be used inside multi-document transactions.可以在多文档事务处理中使用。
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大小限制），请参阅生产注意事项。
Starting in MongoDB 4.4, you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.从MongoDB 4.4开始，如果事务不是跨分片写事务，则可以在多文档事务中创建集合和索引。
Specifically, in MongoDB 4.4 and greater, 具体来说，在MongoDB 4.4及更高版本中，带有db.collection.findOneAndUpdate() with upsert: true can be run on an existing collection or a non-existing collection. upsert:true的db.collection.findOneAndUpdate()可以在现有集合或不存在的集合上运行。If run on a non-existing collection, the operation creates the collection.如果在不存在的集合上运行，则该操作将创建集合。
In MongoDB 4.2 and earlier, the operation must be run on an existing collection.在MongoDB 4.2及更早版本中，操作必须在现有集合上运行。
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.要将写关注点用于事务，请参阅事务和写关注点。
The grades collection contains documents similar to the following: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 }
The following operation finds the first document where 下面的操作会找到第一个name : R. Stiles and increments the score by 5:name : R. Stiles的文档，并将分数增加5：
db.grades.findOneAndUpdate(
{ "name" : "R. Stiles" },
{ $inc: { "points" : 5 } }
)
The operation returns the original document before the update:该操作返回更新前的原始文档：
{ _id: 6319, name: "R. Stiles", "assignment" : 2, "points" : 12 }
If 如果rreturnNewDocument was true, the operation would return the updated document instead.eturnNewDocument为true，则操作将返回更新的文档。
The grades collection contains documents similar to the following: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 }
The following operation updates a document where 以下操作将更新name : "A. MacDyver". name : "A. MacDyver"的文档。The operation sorts the matching documents by 该操作按points ascending to update the matching document with the least points.points升序对匹配文档进行排序，以用最少的点更新匹配文档。
db.grades.findOneAndUpdate(
{ "name" : "A. MacDyver" },
{ $inc : { "points" : 5 } },
{ sort : { "points" : 1 } }
)
The operation returns the original document before the update:该操作返回更新前的原始文档：
{ _id: 6322, name: "A. MacDyver", "assignment" : 2, "points" : 14 }
The following operation uses projection to only display the 以下操作使用投影仅显示返回文档中的_id, points, and assignment fields in the returned document:_id、points和assignment字段：
db.grades.findOneAndUpdate(
{ "name" : "A. MacDyver" },
{ $inc : { "points" : 5 } },
{ sort : { "points" : 1 }, projection: { "assignment" : 1, "points" : 1 } }
)
The operation returns the original document with only the fields specified in the 该操作返回原始文档，其中仅包含projection document and the _id field as it was not explicitly suppressed (_id: 0) in the projection document.projection文档中指定的字段和_id字段，因为它在投影文档中未被显式抑制（_id:0）。
{ "_id" : 6322, "assignment" : 2, "points" : 14 }
The following operation sets a 5ms time limit to complete the update:以下操作设置完成更新的5毫秒时间限制：
try { db.grades.findOneAndUpdate( { "name" : "A. MacDyver" }, { $inc : { "points" : 5 } }, { sort: { "points" : 1 }, maxTimeMS : 5 }; ); } catch(e){ print(e); }
If the operation exceeds the time limit, it returns:如果操作超过时间限制，则返回：
Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }
The following operation uses the 如果没有与upsert field to insert the update document if nothing matches the filter:filter匹配的内容，则以下操作使用upsert字段插入更新文档：
try { db.grades.findOneAndUpdate( { "name" : "A.B. Abracus" }, { $set: { "name" : "A.B. Abracus", "assignment" : 5}, $inc : { "points" : 5 } }, { sort: { "points" : 1 }, upsert:true, returnNewDocument : true } ); } catch (e){ print(e); }
The operation returns the following:该操作返回以下内容：
{
"_id" : ObjectId("5789249f1c49e39a8adc479a"),
"name" : "A.B. Abracus",
"assignment" : 5,
"points" : 5
}
If 如果returnNewDocument was false, the operation would return null as there is no original document to return.returnNewDocument为false，则操作将返回null，因为没有要返回的原始文档。
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:以下操作包括collation选项：
db.myColl.findOneAndUpdate(
{ category: "cafe" },
{ $set: { status: "Updated" } },
{ collation: { locale: "fr", strength: 1 } }
);
The operation returns the following document:该操作返回以下文档：
{ "_id" : 1, "category" : "café", "status" : "A" }
arrayFiltersarrayFilters的数组更新操作arrayFilters is not available for updates that use an aggregation pipeline.不可用于使用聚合管道的更新。
Starting in MongoDB 3.6, when updating an array field, you can specify 从MongoDB 3.6开始，在更新数组字段时，可以指定arrayFilters that determine which array elements to update.arrayFilters来确定要更新的数组元素。
arrayFilters Criteriastudents条件arrayFilters is not available for updates that use an aggregation pipeline.不可用于使用聚合管道的更新。
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.findOneAndUpdate() method:grades数组中大于或等于100的所有元素，请在db.collection.findOneAndUpdate()方法中使用带arrayFilters选项的筛选位置运算符$[<identifier>]：
db.students.findOneAndUpdate(
{ grades: { $gte: 100 } },
{ $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 ] }
arrayFilters is not available for updates that use an aggregation pipeline.不可用于使用聚合管道的更新。
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 }
]
}
] )
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一起使用，以修改grade大于或等于85的grades数组中所有元素的mean。
db.students2.findOneAndUpdate(
{ _id : 1 },
{ $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 }
]
}
Starting in MongoDB 4.2, 从MongoDB 4.2开始，db.collection.findOneAndUpdate() can accept an aggregation pipeline for the update. db.collection.findOneAndUpdate()可以接受用于更新的聚合管道。The pipeline can consist of the following stages:管道可包括以下阶段：
$addFields$set$project$unset$replaceRoot$replaceWith。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, 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 }
]
}
] )
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字段计算新的字段total：
db.students2.findOneAndUpdate(
{ _id : 1 },
[ { $set: { "total" : { $sum: "$grades.grade" } } } ], // The $set stage is an alias for ``$addFields`` stage
{ returnNewDocument: true }
)
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
}