db.collection.findOneAndDelete()
带驱动程序的 MongoDB
本页面提供 mongosh
方法的相关信息。要查看 MongoDB 驱动程序中的等效方法,请参阅编程语言的相应页面:
定义
db.collection.findOneAndDelete( filter, options )
根据
filter
和sort
条件删除单个文档,并返回已删除的文档。findOneAndDelete()
方法采用以下形式:db.collection.findOneAndDelete( <filter>, { writeConcern: <document>, projection: <document>, sort: <document>, maxTimeMS: <number>, collation: <document> } ) findOneAndDelete()
方法使用以下参数:Parameter类型说明filter
文档writeConcern
文档可选。表达写关注的文档。省略以使用默认写关注。
{ w: <value>, j: <boolean>, wtimeout: <number> } 有关用法,请参阅使用 WriteConcern 删除文档。
如果是在事务中运行,则请勿显式设置此操作的写关注。要将写关注与事务一起使用,请参阅事务和写关注。
projection
文档可选。待返回字段的子集。
如要返回返回文档中的所有字段,请忽略此参数。
如果投影参数不是文档,则操作会出错。
sort
文档maxTimeMS
数字可选。指定该操作必须完成的时间限制(以毫秒为单位)。如果超出此限制,则会返回错误。collation
文档可选。
指定用于操作的排序规则。
排序规则允许用户为字符串比较指定特定于语言的规则,例如字母大小写和重音符号规则。
排序规则选项的语法如下:
collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } 指定排序规则时,
locale
字段为必填字段;所有其他排序规则字段均为可选字段。有关字段的说明,请参阅排序规则文档。如果未指定排序规则,但集合具有默认排序规则(请参阅
db.createCollection()
),则操作将使用为集合指定的排序规则。如果没有为收集或操作指定排序规则,MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。
您不能为一个操作指定多个排序规则。例如,您不能为每个字段指定不同的排序规则,或者如果执行带排序的查找,则不能使用一种排序规则进行查找而另一种排序规则进行排序。
返回: 返回已删除的文档。
兼容性
此方法可用于以下环境中托管的部署:
MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务
注意
所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息,请参阅不支持的命令。
MongoDB Enterprise:基于订阅、自我管理的 MongoDB 版本
MongoDB Community:源代码可用、免费使用且可自行管理的 MongoDB 版本
行为
文档匹配
findOneAndDelete()
删除集合中与 filter
匹配的第一个文档。sort
参数可用于影响要删除哪个文档。
投射
重要
语言一致性
在调整 find()
和 findAndModify()
投影以便与聚合的 $project
阶段保持一致的过程中:
find()
和findAndModify()
投影可以接受聚合表达式和事务语法。MongoDB 对投影执行额外的限制。有关详细信息,请参阅投影限制。
projection
参数采用以下形式的文档:
{ field1: <value>, field2: <value> ... }
投射 | 说明 |
---|---|
<field>: <1 or true> | 指定包含字段。如果为投影值指定非零整数,则该操作会将该值视为 true 。 |
<field>: <0 or false> | 指定排除某个字段。 |
"<field>.$": <1 or true> | |
<field>: <array projection> | 使用数组投影操作符( 不可用于视图。 |
<field>: <aggregation expression> | 指定投影字段的值。 通过使用聚合表达式和语法(包括使用文本和聚合变量),可以投影新字段或使用新值投影现有字段。
|
嵌入式字段规范
对于嵌入文档中的字段,您可以使用以下任一方式指定字段:
点符号,例如
"field.nestedfield": <value>
嵌套表单,例如
{ field: { nestedfield: <value> } }
_id
字段投影
默认情况下,返回的文档中包含 _id
字段,除非您在投影中显式指定 _id: 0
来隐藏该字段。
包括或排除
projection
不能同时包含包含和排除规范,但 _id
字段除外:
在显式包含字段的投影中,
_id
字段是您可以显式排除的唯一字段。在明确排除字段的投影中,
_id
字段是您可以明确包含的唯一字段;但是,默认情况下包含_id
字段。
有关投影的更多信息,另请参阅:
分片集合
对分片集合使用 db.collection.findOneAndDelete()
时,query
必须在分片键上包含相等条件。
分片集合中的文档可能缺少分片键字段。要定位缺失分片键的文档,可将 null
等值匹配 与其他过滤条件(例如针对 _id
字段)结合使用。例如:
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
事务
db.collection.findOneAndDelete()
可以在分布式事务中使用。
如果是在事务中运行,则请勿显式设置此操作的写关注。要将写关注与事务一起使用,请参阅事务和写关注。
重要
在大多数情况下,与单文档写入操作相比,分布式事务会产生更高的性能成本,并且分布式事务的可用性不应取代有效的模式设计。在许多情况下,非规范化数据模型(嵌入式文档和数组)仍然是数据和使用案例的最佳选择。换言之,对于许多场景,适当的数据建模将最大限度地减少对分布式事务的需求。
有关其他事务使用注意事项(如运行时间限制和 oplog 大小限制),另请参阅生产注意事项。
Oplog 条目
如果 db.collection.findOneAndDelete()
操作成功删除文档,则该操作会为 oplog (操作日志)添加一个条目。如果操作失败或未找到要删除的文档,则该操作不会为 oplog 添加条目。
示例
删除文档
scores
集合包含类似于以下格式的文档:
db.scores.insertMany( [ { _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 }, { _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 }, { _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 }, { _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 }, { _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 }, { _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 } ] )
以下操作会找到第一个文档(其中,name : M. Tagnum
)并将其删除:
db.scores.findOneAndDelete( { "name" : "M. Tagnum" } )
此操作会返回已删除的原始文档:
{ _id: 6312, name: "M. Tagnum", "assignment" : 5, "points" : 30 }
使用 WriteConcern 删除文档
scores
集合包含类似于以下格式的文档:
db.scores.insertMany( [ { _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 } ] )
以下操作使用带以下选项的 db.collection.findOneAndDelete()
方法中的写关注文档:
w:1
用于请求确认写入操作已传播到独立运行 mongod 或副本集主节点。j:true
用于告知w:1
中指定的 MongoDB 实例数量,以将删除写入磁盘日志。wtimeout : 1000
指定写关注的时间限制(以毫秒为单位)。wtimeout
只适用于w
值大于 1 的情况。
db.scores.findOneAndDelete( { name: "A. MacDyver" }, { writeConcern: { w : 1, j : true, wtimeout : 1000 } } )
该操作将返回以下文档:
{ _id: 6305, name: 'A. MacDyver', assignment: 5, points: 24 }
该文档通过指定的 writeConcern 选项被删除。
对文档进行排序和删除
scores
集合包含类似于以下格式的文档:
db.scores.insertMany( [ { _id: 6305, name : "A. MacDyver", "assignment" : 5, "points" : 24 }, { _id: 6308, name : "B. Batlock", "assignment" : 3, "points" : 22 }, { _id: 6312, name : "M. Tagnum", "assignment" : 5, "points" : 30 }, { _id: 6319, name : "R. Stiles", "assignment" : 2, "points" : 12 }, { _id: 6322, name : "A. MacDyver", "assignment" : 2, "points" : 14 }, { _id: 6234, name : "R. Stiles", "assignment" : 1, "points" : 10 } ] )
以下操作首先查找满足下列条件的所有文档:name : "A. MacDyver"
。然后按 points
升序排序,接着删除点值最低的文档:
db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 } } )
此操作会返回已删除的原始文档:
{ _id: 6322, name: "A. MacDyver", "assignment" : 2, "points" : 14 }
投影已删除的文档
以下操作使用投影法,仅返回返回文档中的 _id
和 assignment
字段:
db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 }, projection: { "assignment" : 1 } } )
此操作返回带有assignment
和_id
字段的原始文档:
{ _id: 6322, "assignment" : 2 }
在有时间限制的情况下更新文档
以下操作设置 5 毫秒的时间限制来完成删除:
try { db.scores.findOneAndDelete( { "name" : "A. MacDyver" }, { sort : { "points" : 1 }, maxTimeMS : 5 } ) } catch(e){ print(e) }
如果操作超过时间限制,将会返回:
MongoServerError: operation exceeded time limit: { "ok": 0, "code" : 50, "codeName" : "MaxTimeMSExpired" }
注意
为简洁起见,此错误消息已被缩短。
指定排序规则。
排序规则允许用户为字符串比较指定特定于语言的规则,例如字母大小写和重音符号规则。
集合 myColl
包含以下文档:
db.myColl.insertMany( [ { _id: 1, category: "café", status: "A" }, { _id: 2, category: "cafe", status: "a" }, { _id: 3, category: "cafE", status: "a" } ] )
以下操作包括排序规则选项:
db.myColl.findOneAndDelete( { category: "cafe", status: "a" }, { collation: { locale: "fr", strength: 1 } } );
该操作将返回以下文档:
{ "_id" : 1, "category" : "café", "status" : "A" }