# db.collection.findOne()

在本页面

* [定义](#definition)
* [行为](#behavior)
* [例子](#examples)

## 定义

* `db.collection.` `findOne`(查询，投影)
  * 返回一个满足集合或视图上指定查询条件的文档。如果多个文档满足查询，则此方法根据自然订单返回第一个文档，该文档反映磁盘上文档的 order。在上限集合中，natural order 与 insert order 相同。如果没有文档满足查询，则该方法返回 null。

| 参数           | 类型       | 描述                                                  |
| ------------ | -------- | --------------------------------------------------- |
| `query`      | document | 可选的。使用query operators指定查询选择条件。                      |
| `projection` | document | 可选的。使用投影操作员指定要 return 的字段。省略此参数以 return 匹配文档中的所有字段。 |

`projection`参数采用以下形式的文档：

```
{ field1: <boolean>, field2: <boolean> ... }
```

`<boolean>`可以是以下包含或排除值之一：

* `1`或`true`包括。即使未在投影参数中明确指定字段，findOne()方法也始终包含\_id字段。
* `0`或`false`排除。

projection 参数不能混合 include 和 exclude 规则，而 exception 则排除`_id`字段。

|     |                                                                                                                                      |
| --- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 返回： | 一个文档满足指定为此方法的第一个参数的条件。如果指定`projection`参数，findOne()将返回仅包含`projection`字段的文档。除非您明确排除，否则始终包含`_id`字段。 虽然类似于find()方法，findOne()方法返回文档而不是游标。 |

## 行为

### 客户端断开

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

## 例子

### 使用空查询规范

以下操作从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`参数指定 return 的哪些字段。除非排除属于`_id`字段，否则该参数包含 include 或 exclude 规范，而不是两者。

#### 指定 Return 的字段

以下操作在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));
}
```

译者：李冠飞

校对：


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mongoing.com/can-kao/mongo-shell-methods/collection-methods/db-collection-findone.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.