db.collection.findOne()

在此页面上

定义

兼容性
语法
行为
举例

定义

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

重要

mongosh 方法

本页介绍了 mongosh方法。这不是数据库命令或特定语言驱动程序（例如 Node.js）的文档。

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

对于 MongoDB API 驱动程序，请参阅特定语言的MongoDB 驱动程序文档。

对于传统 mongo Shell 文档，请参阅相应 MongoDB Server 版本的文档：

mongo shell v4.4

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

如果多个文档满足查询条件，该方法会根据自然顺序返回第一个文档，自然顺序反映磁盘上文档的顺序。在固定大小集合中，自然顺序与插入顺序相同。如果没有文档满足查询条件，该方法将返回 null。

如果指定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()方法采用以下参数：

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

行为

客户端断开连接

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

投射

重要

语言一致性

作为使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 } } }` 在版本 4.2 及更早版本中，任何规范值（以前不支持的文档值除外）都被视作 `true` 或 `false` 以指示包含或排除该字段。

嵌入式字段规范

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

点符号，例如 "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 }
)

`findOne`结果文档

不能对findOne()的结果应用游标方法，因为返回的是单个文档。您可以直接访问该文档：

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

在`let`选项中使用变量

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

例如，要定义可在 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() →

定义

重要