# db.collection.insert()

在本页面

* [定义](#definition)
* [行为](#behaviors)
* [例子](#examples)
* [写结果](#writeresult)
* [BulkWriteResult](#bulkwriteresult)

## 定义

* `db.collection.` `insert` ()
  * 将一个或多个文档插入集合中。

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

```
db.collection.insert(
       <document or array of documents>,
       {
         writeConcern: <document>,
         ordered: <boolean>
       }
    )
```

| 参数             | 类型             | 描述                                                                                                                                                  |
| -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`     | 文件或 array      | 要插入集合的文档或 array 文档。                                                                                                                                 |
| `writeConcern` | `writeConcern` | 可选的。表示写关注的文件。省略使用默认写入问题。见写关注。 version 2.6 中的新内容。                                                                                                    |
| `ordered`      | boolean        | 可选的。如果`true`，则在 array 中执行文档的有序插入，如果其中一个文档发生错误，MongoDB 将 return 而不处理 array 中的其余文档。 如果`false`，执行无序的 insert，如果其中一个文档发生错误，继续处理 array 中的其余文档。 默认为`true`。 |

更改 version 2.6：insert()返回包含操作状态的 object。

|     |                                                  |
| --- | ------------------------------------------------ |
| 返回： | 单个插入的写结果 object。 ABulkWriteResult object 用于批量插入。 |

## 行为

### 写关注

insert()方法使用插入命令，该命令使用默认的写关注。要指定其他写入问题，请在 options 参数中包含写入关注点。

### 创建集合

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

### \_id 字段

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

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

### 事务

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

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

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

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

## 例子

以下示例将文档插入`products`集合。如果集合不存在，insert()方法将创建集合。

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

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

```
db.products.insert( { item: "card", qty: 15 } )
```

在 insert 期间，mongod将创建`_id`字段并为其分配唯一的ObjectId value，由插入的文档验证：

```
{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }
```

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

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

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

```
db.products.insert( { _id: 10, item: "box", qty: 20 } )
```

该操作在`products`集合中插入以下文档：

```
{ "_id" : 10, "item" : "box", "qty" : 20 }
```

### 插入多个文档

以下 example 通过将 array 文档传递给insert()方法来执行三个文档的批量插入。默认情况下，MongoDB 执行有序的 insert。对于有序插入，如果在其中一个文档的 insert 期间发生错误，MongoDB 将返回错误而不处理 array 中的其余文档。

array 中的文档不需要具有相同的字段。例如，array 中的第一个文档有一个`_id`字段和一个`type`字段。由于第二个和第三个文档不包含`_id`字段，mongod将在 insert 期间为第二个和第三个文档创建`_id`字段：

```
db.products.insert(
    [
        { _id: 11, item: "pencil", qty: 50, type: "no.2" },
        { item: "pen", qty: 20 },
        { item: "eraser", qty: 25 }
    ]
)
```

该操作插入了以下三个文件：

```
{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }
```

### 执行无序 Insert

以下 example 执行三个文档的无序插入。对于无序插入，如果在其中一个文档的 insert 期间发生错误，MongoDB 将继续插入 array 中的其余文档。

```
db.products.insert(
    [
        { _id: 20, item: "lamp", qty: 50, type: "desk" },
        { _id: 21, item: "lamp", qty: 20, type: "floor" },
        { _id: 22, item: "bulk", qty: 100 }
    ],
    { ordered: false }
)
```

### 覆盖默认写入关注

对副本集的以下操作指定`"w: majority"`的`"w: majority"`，其`wtimeout`为 5000 毫秒，以便该方法在写入传播到大多数表决副本集成员后返回，或者该方法在 5 秒后超时。

在 version 3.0 中更改：在以前的版本中，`majority`指的是副本集的大多数成员而不是大多数投票成员。

```
db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)
```

## 写结果

传递单个文档时，insert()返回`WriteResult` object。

### 成功的结果

insert()返回包含操作状态的写结果 object。成功后，写结果 object 包含有关插入文档数量的信息：

```
WriteResult({ "nInserted" : 1 })
```

### 写关注错误

如果insert()方法遇到写入关注错误，则结果包括WriteResult.writeConcernError字段：

```
WriteResult({
    "nInserted" : 1,
    "writeConcernError" : {
        "code" : 64,
        "errmsg" : "waiting for replication timed out at shard-a"
    }
})
```

### 与写关注无关的错误

如果insert()方法遇到 non-write 关注错误，则结果包括WriteResult.writeError字段：

```
WriteResult({
    "nInserted" : 0,
    "writeError" : {
        "code" : 11000,
        "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_  dup key: { : 1.0 }"
    }
})
```

## BulkWriteResult

传递 array 文档时，insert()返回BulkWriteResult() object。有关详细信息，请参阅BulkWriteResult()。

译者：李冠飞

校对：


---

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