Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs 菜单
Docs 主页
/
开发中
/
mongosh 方法
Docs 主页
/
开发中
/
mongosh 方法
Docs 主页
/
开发中
/
mongosh 方法

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

带驱动程序的 MongoDB

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

C#Java SyncNode.jsPyMongoCC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

定义

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

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

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

匹配文档的数量
查询计划
结果

0

Any

该方法返回 null

1

Any

该方法返回满足指定查询条件的文档。

2 或更多

集合扫描(collection scan)

该方法根据自然顺序返回第一个文档。在固定大小集合中，自然顺序与插入顺序相同。

2 或更多

索引扫描

该方法返回从索引中检索到的第一个文档。

重要

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

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

注意

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

兼容性

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

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

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

语法

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

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

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

Parameter
类型
说明

query

文档

可选。使用查询操作符指定查询选择标准。

projection

文档

可选。 使用投影操作符指定要返回的字段。省略此参数可返回匹配文档中的所有字段。 有关详细信息，请参阅投影。

options

文档

可选。为查询指定其他选项。这些选项可修改查询行为以及结果的返回方式。要查看可用选项，请参阅 FindOptions。

行为

客户端断开连接

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

投射

重要

语言一致性

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

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 } } }

注意

您可以通过两种方式为 find() 和 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

在此页面上