db.collection.findOne()

在此页面上

定义

兼容性
语法
行为
示例

带驱动程序的 MongoDB

本页面提供 mongosh 方法的相关信息。要查看 MongoDB 驱动程序中的等效方法，请参阅编程语言的相应页面：

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

定义

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

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

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

匹配文档的数量	查询计划	结果
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

定义

重要

注意

兼容性

语法

行为