Docs 菜单
Docs 主页
/
MongoDB Manual
/ / /

find

在此页面上

  • 定义
  • 兼容性
  • 语法
  • 行为
  • 示例
find

执行查询,然后返回第一批结果和游标 ID,客户端可据此构造游标。

提示

mongosh 中,还可以通过 db.collection.find()db.collection.findOne() 助手方法运行此命令。

辅助方法对 mongosh 用户来说很方便,但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段,请使用数据库命令。

此命令可用于以下环境中托管的部署:

  • MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务

重要

此命令在 M 0 、 M 2和 M 5集群中提供有限支持。 有关更多信息,请参阅不支持的命令。

find 命令采用以下语法:

5.0 版本中的更改

db.runCommand(
{
find: <string>,
filter: <document>,
sort: <document>,
projection: <document>,
hint: <document or string>,
skip: <int>,
limit: <int>,
batchSize: <int>,
singleBatch: <bool>,
comment: <any>,
maxTimeMS: <int>,
readConcern: <document>,
max: <document>,
min: <document>,
returnKey: <bool>,
showRecordId: <bool>,
tailable: <bool>,
oplogReplay: <bool>,
noCursorTimeout: <bool>,
awaitData: <bool>,
allowPartialResults: <bool>,
collation: <document>,
allowDiskUse : <bool>,
let: <document> // Added in MongoDB 5.0
}
)

该命令接受以下字段:

字段
类型
说明
find
字符串
要查询的集合或视图的名称。
filter
文档
可选。查询谓词。如未指定,则集合中的所有文档都将与谓词匹配。
文档
可选。结果的排序规范。
projection
文档

可选。用于确定要在返回的文档中包含哪些字段的投影规范。请参阅投影投影操作符

视图上的 find() 操作不支持以下查询和投影操作符

hint
字符串或文档

可选。索引规范。以字符串形式指定索引名称或索引键模式。如果指定,查询系统将只考虑使用提示索引的计划。

除以下例外情况外,如果命令包含 min 和/或 max 字段,则必须使用 hint;如果 filter_id 字段 { _id: <value> } 的相等条件,则在使用 min 和/或 max 时,hint 不是必需的。

skip
正整数
可选。要跳过的文档数。默认值为 0。
limit
Non-negative integer
可选。要返回的最大文档数。如果未指定,则默认为无限制。限制为 0 相当于不设限制。
batchSize
non-negative integer

可选。第一批中要返回的文档数量。默认为 101。batchSize 为 0 是指将建立游标,但第一批不会返回任何文档。

与之前的传输协议版本不同,find 命令的 batchSize 为 1 不会关闭游标。

singleBatch

布尔
可选。确定是否在第一次批处理后关闭游标。默认值为 false。
comment
any

可选。用户提供的待附加到该命令的注释。设置后,该注释将与该命令的记录一起出现在以下位置:

注释可以是任何有效的 BSON 类型(字符串、整型、对象、数组等)。

find 命令上设置的任何注释都将由在 find 游标上运行的任何后续 getMore 命令继承。

maxTimeMS
non-negative integer

可选。

指定时间限制(以毫秒为单位)。如果您未指定 maxTimeMS 值,操作将不会超时。如果值为 0 ,则显式指定默认无限制行为。

MongoDB 使用与 db.killOp() 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。

指定 linearizable read concern 时,如果大多数数据承载节点不可用,则始终使用 maxTimeMSmaxTimeMS 确保操作不会无限期受阻,而且在无法满足读关注时返回错误。

readConcern
文档

可选。指定读关注

readConcern 选项的语法如下:readConcern: { level: <value> }

可能的读关注级别是:

有关读关注级别的更多信息,请参阅读关注级别

getMore 命令使用原始 find 命令中指定的 readConcern 级别。

max
文档

可选。特定索引的独占上限。请参阅 cursor.max() 了解详细信息。

要使用 max 字段,该命令还必须使用 hint ,除非指定的 filter_id 字段 { _id: <value> }上的相等条件。

min
文档

可选。特定索引的包含下限。请参阅 cursor.min() 了解详细信息。

要使用 min 字段,该命令还必须使用 hint ,除非指定的 filter_id 字段 { _id: <value> }上的相等条件。

returnKey
布尔
可选。如果为 true,则只返回结果文档中的索引键。默认值为 false。如果 returnKey 为 true 且 find 命令没有使用索引,则返回的文档将为空。
showRecordId
布尔
可选。确定是否返回每个文档的记录标识符。如果为 true,则将字段 $recordId 添加到返回文档。
tailable
布尔
可选。返回固定大小集合的可追加游标
awaitData
布尔
可选。 与 tailable 选项结合使用,可在数据末尾暂时区块游标上的getMore命令,而不是不返回数据。 超时一段时间后, find将正常返回。
noCursorTimeout
布尔
可选。阻止服务器在一段不活动时间(30 分钟)后将非会话空闲游标设置为超时。对于属于会话的游标,处理会被忽略。有关更多信息,请参阅会话空闲超时。
布尔

可选。对于针对分片集合的查询,如果一个或多个查询的分片不可用,则允许该命令(或后续 getMore 命令)返回部分结果,而非错误。

如果 find(或后续的 getMore 命令)因查询的分片不可用而返回部分结果,则查找输出会包含 partialResultsReturned 指示字段。如果查询的分片可用于初始 find 命令,但一个或多个分片不可用于后续的 getMore 命令,则只有在分片不可用时运行的 getMore 命令才会在其输出中包含 partialResultsReturned

collation
文档

可选。

指定用于操作的排序规则

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

排序规则选项的语法如下:

collation: {
locale: <string>,
caseLevel: <boolean>,
caseFirst: <string>,
strength: <int>,
numericOrdering: <boolean>,
alternate: <string>,
maxVariable: <string>,
backwards: <boolean>
}

指定排序规则时,locale 字段为必填字段;所有其他排序规则字段均为可选字段。有关字段的说明,请参阅排序规则文档

如果未指定排序规则,但集合具有默认排序规则(请参阅 db.createCollection()),则操作将使用为集合指定的排序规则。

如果没有为收集或操作指定排序规则,MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

您不能为一个操作指定多个排序规则。例如,您不能为每个字段指定不同的排序规则,或者如果执行带排序的查找,则不能使用一种排序规则进行查找而另一种排序规则进行排序。

布尔

可选。

使用此选项可以覆盖特定查询的 allowDiskUseByDefault。您可以使用此选项执行以下任一操作:

  • 禁止在默认允许使用磁盘的系统上使用磁盘。

  • 支持在默认情况下禁止使用磁盘的系统上使用磁盘。

从 MongoDB 6.0 开始,如果 allowDiskUseByDefault 设置为 true,并且服务器需要超过 100 MB 的内存用于管道执行阶段,那么 MongoDB 会自动将临时文件写入磁盘,除非查询指定了 { allowDiskUse: false }

有关详细信息,请参阅allowDiskUseByDefault

allowDiskUse 如果 MongoDB 可以使用索引满足指定的排序或者阻塞排序需要少于 100 MB 的内存,则不会有任何影响。

有关 allowDiskUse 的更完整文档,请参见 cursor.allowDiskUse()

有关大型阻塞排序的内存限制的更多信息,请参阅排序和索引使用

文档

可选。

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

文档语法为:

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

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

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

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

有关使用 let 和变量的完整示例,请参阅let 中使用变量

版本 5.0 中的新增功能

此命令返回一个包含游标信息的文档,包括游标 ID 和第一批文档。例如,当针对分片集合运行时,将返回以下文档:

{
"cursor" : {
"firstBatch" : [
{
"_id" : ObjectId("5e8e2ca217b5324fa9847435"),
"zipcode" : "20001",
"x" : 1
},
{
"_id" : ObjectId("5e8e2ca517b5324fa9847436"),
"zipcode" : "30001",
"x" : 1
}
],
"partialResultsReturned" : true,
"id" : NumberLong("668860441858272439"),
"ns" : "test.contacts"
},
"ok" : 1,
"operationTime" : Timestamp(1586380205, 1),
"$clusterTime" : {
"clusterTime" : Timestamp(1586380225, 2),
"signature" : {
"hash" : BinData(0,"aI/jWsUVUSkMw8id+A+AVVTQh9Y="),
"keyId" : NumberLong("6813364731999420435")
}
}
}
字段
说明
cursor

包含游标信息,包括游标 id 以及文档的 firstBatch

如果针对分片集合的操作由于所查询的分片不可用而返回部分结果,则 cursor 文档会包含 partialResultsReturned 字段。要返回由于所查询的分片不可用而导致的部分结果(而不是错误),则在运行 find 命令时必须将 allowPartialResults 设为 true。请参阅 allowPartialResults

如果查询的分片一开始可用于 find 命令,但在随后的 getMore 命令中一个或多个分片不可用,则只有在不可用的查询分片在输出中包含 partialResultsReturned 标志时,才会运行 getMore 命令。

"ok"
表明命令是成功(1)还是失败(0)。

除了上述特定于 find 的字段外,db.runCommand() 还包括副本集和分片集群的以下信息:

  • $clusterTime

  • operationTime

有关详细信息,请参阅 db.runCommand() 结果

从 MongoDB 5.1 开始,不再忽略无效的 $regex options 选项。此更改使 $regex optionsaggregate 命令和投影查询所使用的 $regex 更加一致。

对于在一个会话内创建的游标,不能在该会话外调用 getMore

同样,对于在会话外创建的游标,不能在会话内调用 getMore

MongoDB 驱动程序和 mongosh 将所有操作与服务器会话相关联,未确认的写入操作除外。对于未与会话显式关联的操作(即使用 Mongo.startSession()),MongoDB 驱动程序和 mongosh 会创建隐式会话并将其与该操作关联。

如果会话空闲时间超过 30 分钟,MongoDB Server 会将该会话标记为已过期,并可能随时将其关闭。当 MongoDB Server 关闭会话时,它还会终止任何正在进行的操作并打开与会话关联的游标。这包括使用超过 30 分钟的 noCursorTimeout()maxTimeMS() 配置的游标。

对于返回游标的操作,如果游标的空闲时间可能超过 30 分钟,则使用 Mongo.startSession() 在显式会话中发出操作,并使用 refreshSessions 命令定期刷新会话。更多信息,请参阅会话空闲超时

find 可以在分布式事务中使用。

  • 对于在 ACID 事务外部创建的游标,无法在 ACID 事务内部调用 getMore

  • 对于在事务中创建的游标,无法在事务外部调用 getMore

重要

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

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

从 MongoDB 4.2 开始,如果在操作完成之前,发出 find 的客户端断开连接,MongoDB 将使用killOpfind 标记为终止。

使用 Stable API V1 时,不支持以下 find 命令字段:

  • awaitData

  • max

  • min

  • noCursorTimeout

  • oplogReplay

  • returnKey

  • showRecordId

  • tailable

从 MongoDB 6.0 开始,索引筛选器会使用之前使用 planCacheSetFilter 命令设置的排序规则

从 MongoDB 8.0开始,使用查询设置而不是添加索引筛选器。 从 MongoDB 8.0开始,索引筛选器已弃用。

查询设置的功能比索引筛选器更多。 此外,索引筛选器不是持久性的,您无法轻松地为所有集群节点创建索引筛选器。 要添加查询设置并探索示例,请参阅setQuerySettings

从MongoDB 7.3开始,当您在带有singleBatch: truebatchSize: 1选项的视图上使用 find 命令时,不再返回游标。 在MongoDB的早期版本中,即使设立单个批处理选项设置为true ,这些查找查询也会返回游标。

8.0版本新增

您可以使用查询设置来设置索引提示、设置操作拒绝过滤器以及其他字段。这些设置将应用于整个集群上的查询结构。在关闭之后,集群将保留这些设置。

在查询规划期间,查询优化器将使用查询设置作为附加输入,这样会影响为运行查询而选择的计划。您还可以使用查询设置来阻塞查询结构。

要添加查询设置并探索示例,请参阅 setQuerySettings

您可以为 finddistinctaggregate 命令添加查询设置。

查询设置具有更多功能,相比已弃用的索引过滤器而言是您的首选。

要删除查询设置,请使用 removeQuerySettings。要获取查询设置,请在一个聚合管道中使用一个 $querySettings 阶段。

以下命令运行 find 命令过滤 rating 字段和 cuisine 字段。该命令包含一个 projection,仅返回匹配文档中的以下字段:_idnameratingaddress 字段。

此命令按 name 字段对结果集中的文档进行排序,并将结果集限制为 5 个文档。

db.runCommand(
{
find: "restaurants",
filter: { rating: { $gte: 9 }, cuisine: "italian" },
projection: { name: 1, rating: 1, address: 1 },
sort: { name: 1 },
limit: 5
}
)

若要覆盖 "local" 的默认读取关注级别,请使用 readConcern 选项。

对副本集执行以下操作可以指定读关注 "majority",以读取确认已写入大多数节点的数据的最新副本。

db.runCommand(
{
find: "restaurants",
filter: { rating: { $lt: 5 } },
readConcern: { level: "majority" }
}
)

无论读关注级别如何,节点上的最新数据可能无法反映系统中数据的最新版本。

getMore 命令使用原始 find 命令中指定的 readConcern 级别。

您可以使用 cursor.readConcern() 方法为 mongosh 方法 db.collection.find() 指定 readConcern

db.restaurants.find( { rating: { $lt: 5 } } ).readConcern("majority")

有关可用读关注的更多信息,请参阅读关注

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

以下操作使用指定排序规则运行 find 命令:

db.runCommand(
{
find: "myColl",
filter: { category: "cafe", status: "a" },
sort: { category: 1 },
collation: { locale: "fr", strength: 1 }
}
)

mongosh 提供了 cursor.collation() 来指定 db.collection.find() 操作的排序规则

版本 5.0 中的新增功能

要定义可在命令中其他位置访问的变量,请使用 let 选项。

注意

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

创建集合 cakeFlavors

db.cakeFlavors.insertMany( [
{ _id: 1, flavor: "chocolate" },
{ _id: 2, flavor: "strawberry" },
{ _id: 3, flavor: "cherry" }
] )

以下示例在 let 中定义了一个 targetFlavor 变量,并使用该变量检索巧克力蛋糕口味:

db.cakeFlavors.runCommand( {
find: db.cakeFlavors.getName(),
filter: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
let : { targetFlavor: "chocolate" }
} )

后退

删除