Docs 菜单
Docs 主页
/
MongoDB Manual
/
参考
/
mongosh 方法
/
集合

db.collection.findOne()

在此页面上

  • 定义
  • 兼容性
  • 语法
  • 行为
  • 示例

带驱动程序的 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。

行为

客户端断开连接

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

投射

重要

语言一致性

在调整 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 } } }

嵌入式字段规范

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

  • 点符号，例如 "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 选项中使用变量

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

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