db.collection.findOne()

在此页面上

定义

兼容性
语法
行为
示例

定义

db.collection.findOne(query, projection, options)

重要

mongosh 方法

本页面提供 mongosh 方法的相关信息。这不是数据库命令或特定语言驱动程序（例如 Node.js）的相关文档。

有关数据库命令，请参阅 find 命令。

如需了解 MongoDB API 驱动程序，请参阅特定语言的 MongoDB 驱动程序文档。

在集合或视图中返回一个满足指定查询条件的文档。

返回的文档可能会有所不同，这取决于符合查询条件的文档数量和使用的查询计划：

匹配文档的数量	查询计划	结果
0	Any	该方法返回 `null`
1	Any	该方法返回满足指定查询条件的文档。
2或更多	集合扫描(collection scan)	该方法根据自然顺序返回第一个文档。在固定大小集合中，自然顺序与插入顺序相同。
2或更多	索引扫描	该方法返回从索引中检索到的第一个文档。

重要

如果将查询计划更改为使用不同的索引，则该方法可能会返回不同的文档。如果您的使用案例要求以一致的方式选择特定记录，则必须使用 options文档来指定排序。有关在options 文档中使用findOne() 的详细信息，请参阅示例。

如果您指定 projection 参数，findOne() 将返回仅包含 projection 字段的文档。除非您显式排除 _id 字段，否则该字段将始终包含在内。

注意

虽然与 find() 方法类似，但 findOne() 方法返回的是文档而不是游标。

兼容性

可以使用 db.collection.findOne() 查找托管在以下环境中的部署：

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

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

findOne() 方法采用以下形式：

db.collection.findOne( <query>, <projection>, <options> )

findOne() 方法使用以下参数：

Parameter	类型	说明
`query`	文档	可选。使用查询操作符指定查询选择标准。
`projection`	文档	可选。使用投影操作符指定要返回的字段。忽略此参数可返回匹配文档中的所有字段。有关详细信息，请参阅投影。
`options`	文档	可选。指定查询的附加选项。这些选项可修改查询行为以及返回结果的方式。若要查看可用选项，请参阅 FindOptions。

行为

客户端断开连接

从 MongoDB 4.2 开始，如果在操作完成之前，发出 db.collection.findOne() 的客户端断开连接，MongoDB 将使用killOp 将 db.collection.findOne() 标记为终止。

投射

重要

语言一致性

在调整 find() 和 findAndModify() 投影以便与聚合的 $project 阶段保持一致的过程中：

find() 和 findAndModify() 投影可以接受聚合表达式和事务语法。
MongoDB 对投影执行额外的限制。有关详细信息，请参阅投影限制。

projection 参数确定匹配文档中返回哪些字段。projection 参数采用以下形式的文档：

{ field1: <value>, field2: <value> ... }

投射	说明
`<field>: <1 or true>`	指定包含字段。如果为投影值指定非零整数，则该操作会将该值视为`true`。
`<field>: <0 or false>`	指定排除某个字段。
`"<field>.$": <1 or true>`	使用 `$` 数组投影操作符返回与数组字段的查询条件匹配的第一个元素。如果您为该投影值指定非零整数，则该操作会将该值视为 `true`。不可用于视图。
`<field>: <array projection>`	使用数组投影操作符（`$elemMatch`、`$slice`）指定要包含的数组元素。不可用于视图。
`<field>: <$meta expression>`	使用 `$meta` 操作符表达式可指定包含可用的 `per-document metadata`。不可用于视图。
`<field>: <aggregation expression>`	指定投影字段的值。通过使用聚合表达式和语法（包括使用文本和聚合变量），可以投影新字段或使用新值投影现有字段。如果您为投影值指定非数字、非布尔文字（例如文字字符串、数量或操作符表达式），则该字段将使用新值进行投影，例如： `{ field: [ 1, 2, 3, "$someExistingField" ] }` `{ field: "New String Value" }` `{ field: { status: "Active", total: { $sum: "$existingArray" } } }` 要投影字段的字面值，请使用 `$literal` 聚合表达式；例如： `{ field: { $literal: 5 } }` `{ field: { $literal: true } }` `{ field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }`

嵌入式字段规范

对于嵌入文档中的字段，您可以使用以下任一方式指定字段：

点符号，例如 "field.nestedfield": <value>
嵌套表单，例如 { field: { nestedfield: <value> } }

`_id` 字段投影

默认情况下，返回的文档中包含 _id 字段，除非您在投影中显式指定 _id: 0 来隐藏该字段。

包括或排除

projection 不能同时包含包含和排除规范，但 _id 字段除外：

在显式包含字段的投影中，_id 字段是您可以显式排除的唯一字段。
在明确排除字段的投影中，_id字段是您可以明确包含的唯一字段；但是，默认情况下包含_id字段。

有关投影的更多信息，另请参阅：

示例

使用空查询规范

以下操作从 BIOS 集合中返回单个文档：

db.bios.findOne()

附带查询规范

以下操作返回 BIOS 集合中的第一个匹配文档，其中嵌入式文档 name 中的字段 first 以字母 G 开头，或者字段 birth 小于 new Date('01/01/1945')：

db.bios.findOne(
   {
     $or: [
            { 'name.first' : /^G/ },
            { birth: { $lt: new Date('01/01/1945') } }
          ]
   }
)

投影

projection 参数指定要返回的字段。该参数包括包含或排除规范，但不能同时包括两者，除非排除是针对 _id 字段。

指定待返回的字段

以下操作可在 BIOS 集合中查找文档并仅返回 name、contribs 和 _id 字段：

db.bios.findOne(
    { },
    { name: 1, contribs: 1 }
)

返回除已排除字段之外的所有字段

以下操作返回 BIOS 集合中的文档（contribs 字段包含元素 OOP），并返回除 _id 字段、name 嵌入式文档中的 first 字段和 birth 之外的所有字段：

db.bios.findOne(
   { contribs: 'OOP' },
   { _id: 0, 'name.first': 0, birth: 0 }
)

带有选项

以下操作使用sort 选项返回已排序bios 集合中的第一个匹配文档。在此示例中，集合按 birth 升序排序。

db.bios.findOne(
   { },
   { },
   { sort: { birth: 1 } }
)

`findOne`结果文档

由于返回的是单个文档，因此无法对 findOne() 的结果应用游标方法。可以直接访问该文档：

var myDocument = db.bios.findOne();
if (myDocument) {
   var myName = myDocument.name;
   print (tojson(myName));
}

在`let` 选项中使用变量<a class=\" \" href=\" \" title=\" \"><svg xmlns=\" \" width=\" \" height=\" \" fill=\" \" viewbox=\" \" class=\" \" role=\" \" aria-label=\" \"><path fill=\" \" d=\" \"> <path fill=\" \" d=\" \">

您可以指定查询选项来修改查询行为并指示如何返回结果。

例如，要定义可在 findOne 方法中的其他位置访问的变量，请使用 let 选项。要使用变量过滤结果，必须在 $expr 操作符中访问该变量。

创建集合 cakeFlavors：

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

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

db.cakeFlavors.findOne(
   { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   { _id: 0 },
   { let : { targetFlavor: "chocolate" }
} )

输出：

{ flavor: 'chocolate' }

要查看所有可用的查询选项，请参阅 FindOptions。

后退

db.collection.findAndModify

来年

db.collection.findOneAndDelete

定义

重要