# db.collection.insertOne()

在本页面

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

## 定义

* `db.collection.` `insertOne` ()
  * version 3.2 中的新内容。

将文档插入集合中。

insertOne()方法具有以下语法：

```
db.collection.insertOne(
    <document>,
    {
        writeConcern: <document>
    }
)
```

| 参数             | 类型       | 描述                                                                     |
| -------------- | -------- | ---------------------------------------------------------------------- |
| `document`     | document | 要插入集合的文档。                                                              |
| `writeConcern` | document | 可选的。表示写关注的文件。省略使用默认写入问题。 如果在事务中运行，请不要为操作明确设置写关注点。要对事务使用写关注，请参见 事务和写关注。 |

|     |                                                                                                       |
| --- | ----------------------------------------------------------------------------------------------------- |
| 返回： | 包含以下内容的文档： 一个布尔值`acknowledged`，`true`好像该操作在运行时带有 写关注点，或者`false`禁用了写关注点。 `insertedId`具有`_id`插入文档的值的字段。 |

## 行为

### 集合创建

如果集合不存在，则insertOne()方法将创建集合。

### \_id 字段

如果文档未指定\_id字段，则mongod将添加`_id`字段，并在插入之前为文档指定唯一的ObjectId。大多数驱动程序创建一个 ObjectId 并插入`_id`字段，但如果驱动程序或 application 没有，mongod将创建并填充`_id`。

如果文档包含`_id`字段，则`_id` value 在集合中必须是唯一的，以避免重复的 key 错误。

### Explainability

insertOne()与db.collection.explain()不兼容。

请改用insert()。

### 错误处理

出错时，insertOne()抛出`writeError`或`writeConcernError` exception。

### 事务

`db.collection.insertOne()`可以在多文档交易中使用。

集合必须已经存在。事务中不允许执行会导致创建新集合的插入操作。

如果在事务中运行，请不要为操作明确设置写关注点。要对事务使用写关注，请参见 事务和写关注。

> **重要**
>
> 在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应替代有效的架构设计。在许多情况下， 非规范化数据模型（嵌入式文档和数组）将继续是您的数据和用例的最佳选择。也就是说，在许多情况下，适当地对数据建模将最大程度地减少对多文档交易的需求。
>
> 有关其他事务使用方面的注意事项（例如运行时限制和操作日志大小限制），另请参见 生产注意事项。

## 例子

### 插入文档而不指定\_id 字段

在以下 example 中，传递给insertOne()方法的文档不包含`_id`字段：

```
try {
    db.products.insertOne( { item: "card", qty: 15 } );
} catch (e) {
    print (e);
};
```

该操作返回以下文档：

```
{
    "acknowledged" : true,
    "insertedId" : ObjectId("56fc40f9d735c28df206d078")
}
```

由于文档不包含`_id`，mongod创建并添加`_id`字段并为其分配唯一的ObjectId value。

当操作为 run 时，`ObjectId`值特定于机器和 time。因此，您的值可能与 example 中的值不同。

### 插入指定\_id 字段的文档

在下面的示例中，传递给insertOne()方法的文档包含`_id`字段。 `_id`的 value 在集合中必须是唯一的，以避免重复的 key 错误。

```
try {
    db.products.insertOne( { _id: 10, item: "box", qty: 20 } );
} catch (e) {
    print (e);
}
```

该操作返回以下内容：

```
{ "acknowledged" : true, "insertedId" : 10 }
```

为的任何 key 插入重复的 value，例如`_id`，会抛出 exception。以下尝试使用已存在的`_id` value 插入文档：

```
try {
    db.products.insertOne( { _id: 10, "item" : "packing peanuts", "qty" : 200 } );
} catch (e) {
    print (e);
}
```

由于`_id: 10`已存在，因此抛出以下 exception：

```
WriteError({
    "index" : 0,
    "code" : 11000,
    "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 10.0 }",
    "op" : {
        "_id" : 10,
        "item" : "packing peanuts",
        "qty" : 200
    }
})
```

### 增加写作关注

给定三个成员副本集，以下操作指定`majority` `wtimeout`，`wtimeout` `100`：

```
try {
    db.products.insertOne(
        { "item": "envelopes", "qty": 100, type: "Self-Sealing" },
        { writeConcern: { w : "majority", wtimeout : 100 } }
    );
} catch (e) {
    print (e);
}
```

如果确认时间超过`wtimeout`限制，则抛出以下 exception：

```
WriteConcernError({
    "code" : 64,
    "errInfo" : {
        "wtimeout" : true
    },
    "errmsg" : "waiting for replication timed out"
})
```

> **也可以看看**
>
> 要插入多个文档，请参阅db.collection.insertMany()

译者：李冠飞

校对：


---

# 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-insertone.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.