db. 集合.findOne()（mongosh方法）

带驱动程序的 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 或更多	索引扫描	该方法返回从索引中检索到的第一个文档。

重要

If the query plan changes to use a different index, the method may return a different document. If your use case requires that a particular record is chosen consistently, you must use the options document to specify a sort. For details on using findOne() with an options document, see the example.

If you specify a projection parameter, findOne() returns a document that only contains the projection fields. The _id field is always included unless you explicitly exclude it.

注意

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

兼容性

此方法可用于以下环境中托管的部署：

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

注意

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

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

语法

db.collection.findOne() 采用以下形式：

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

db.collection.findOne() 使用以下参数：

Parameter	类型	说明
`query`	文档	可选。使用查询操作符指定查询选择标准。
`projection`	文档	Optional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document. For details, see Projection.
`options`	文档	可选。指定查询的附加选项。这些选项可修改查询行为以及返回结果的方式。要查看可用的选项，请参阅 FindOptions。

行为

客户端断开连接

如果发出 findOne() 的客户端在操作完成之前断开连接，则MongoDB使用killOp将 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 } } }`

注意

You can specify projection in two ways for find() and findOne():

设置 projection 参数
将 options 参数设置为 projection

如果同时指定这两个参数，则 projection 参数优先。要使用 options.projection，请将 projection 参数设立为 null 或 undefined。

嵌入式字段规范

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

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

`_id` 字段投影

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

包括或排除

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

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

示例

本页上的示例使用来自 sample_mflix 数据集的数据。有关如何将此数据集加载到您的自管理 MongoDB 部署中的详细信息，请参阅加载示例数据集。如果您对示例数据库进行了任何修改，您可能需要删除并重新创建数据库，才能运行此页面上的示例。

使用空查询规范

以下操作返回 sample_mflix数据库中 movies集合中的单个文档：

db.movies.findOne()

附带查询规范

以下操作返回 movies 集合中的第一个匹配文档，其中 title 字段以字母“T”开头或 year 字段小于 1950：

db.movies.findOne(
   {
      $or: [
            { title: /^T/ },
            { year: { $lt: 1950 } }
            ]
   }
)

投影

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

指定待返回的字段

以下操作在 movies集合中查找文档，并仅返回 title、genres 和 imdb 字段：

db.movies.findOne(
   { },
   { title: 1, genres: 1, imdb: 1 }
)

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

以下操作返回 movies集合中的文档，其中 cast数组包含 "Al Pacino"。投影将返回除 _id字段、votes imdb嵌入式文档中的字段以及fullplot 字段之外的所有字段：

db.movies.findOne(
   { cast: 'Al Pacino' },
   { _id: 0, 'imdb.votes': 0, fullplot: 0 }
)

带有选项

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

db.movies.findOne(
   { },
   { },
   { sort: { year: 1 } }
)

`findOne` 结果文档

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

var myDocument = db.movies.findOne();
if (myDocument) {
   var myTitle = myDocument.title;
   print(myTitle);
}

在 `let` 选项中使用变量

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

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

以下示例在 let 中定义了一个 targetTitle 变量，并使用该变量检索标题为 "The Godfather" 的电影：

db.movies.findOne(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   { _id: 0, title: 1, year: 1 },
   { let : { targetTitle: "The Godfather" } }
)

{ year: 1972, title: 'The Godfather' }

后退

db.collection.findAndModify

来年

db.collection.findOneAndDelete