db. 集合()（mongosh方法）

重要

已弃用的 mongosh 方法

此方法在 mongosh 中已弃用。有关替代方法，请参阅与旧版 mongo Shell 的兼容性更改。

定义

db.collection.insert()

将一个或多个文档插入集合中。

返回：

单次插入的 WriteResult 对象。
用于批量插入操作的 BulkWriteResult 对象。

语法

db.collection.insert() 通过以下语法实现：

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

参数

Parameter	类型	说明
`document`	文档或数组	要插入到集合中的文档或文档数组。
`writeConcern`	文档	可选。表达写关注（write concern）的文档。省略使用默认写关注（write concern）。请参阅写关注。如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。
`ordered`	布尔	可选。如果为 `true`，则对数组中的文档执行有序插入，如果其中一个文档发生错误，MongoDB 将返回，而不处理数组中的其余文档。如果为 `false`，则执行无序插入，如果其中一个文档发生错误，则继续处理数组中的其余文档。默认值为 `true`。

行为

写关注

insert() 方法使用 insert 命令，该命令使用默认的写关注。要指定不同的写关注，请将写关注包含在 options 参数中。

集合与`_id`字段创建

如果该集合不存在，则insert()会创建该集合。

如果文档未指定 _id 字段，则 mongod 会添加 _id 字段，并为该文档分配唯一的 ObjectId()。大多数驱动程序都会创建一个 ObjectId 并插入 _id 字段，如果驱动程序或应用程序不这样做，则 mongod 将创建并填充 _id。

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

事务

insert() 可用于分布式事务。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在事务中创建集合

如果事务不是跨分片写事务，则可以在分布式事务中创建集合和索引。

如果在事务中对不存在的集合指定插入操作，则 MongoDB 会隐式创建该集合。

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

Oplog 条目

如果 insert() 操作成功插入文档，则该操作会为 oplog（操作日志）添加一个条目。如果操作失败，则该操作不会为 oplog 添加条目。

示例

本页上的示例使用sample_mflix示例数据集中的数据。有关如何将此数据集加载到自管理MongoDB 部署中的详细信息，请参阅加载示例数据集。如果对示例数据库进行了任何修改，则可能需要删除并重新创建数据库才能运行本页上的示例。

插入文档而不指定 `_id` 字段

以下示例将没有 _id字段的文档插入到 movies集合中：

db.movies.insert( { title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] } )

{
  acknowledged: true,
  insertedIds: { '0': "..." }
}

由于插入的文档不包含_id mongod_id，因此ObjectId() 创建并添加字段，并为其分配唯一的值。

ObjectId 值特定于运行操作时的设备和时间。因此，您的值可能与示例中的值不同。

插入指定 `_id` 字段的文档

以下示例指定插入 movies集合的文档中的 _id字段。 _id 的值在集合中必须是唯一的，以避免重复键错误。

db.movies.insert( { _id: 10, title: "Inception", year: 2010 } )

{
  acknowledged: true,
  insertedIds: { '0': 10 }
}

插入多个文档

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

第一个文档指定了一个_id 字段。由于第二个和第三个文档不包含_id 字段，因此mongod _id在插入期间为这些文档创建并添加字段：

db.movies.insert(
   [
     { _id: 11, title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] },
     { title: "The Matrix", year: 1999 },
     { title: "Interstellar", year: 2014 }
   ]
)

{
  acknowledged: true,
  insertedIds: {
    '0': 11,
    '1': "...",
    '2': "..."
  }
}

执行无序插入

以下示例无序插入三个文档。对于无序插入，如果在插入其中一个文档的过程中出现错误，MongoDB 会继续插入数组中剩余的文档。

db.movies.insert(
   [
     { _id: 20, title: "2001: A Space Odyssey", year: 1968 },
     { _id: 21, title: "A Clockwork Orange", year: 1971 },
     { _id: 22, title: "The Shining", year: 1980 }
   ],
   { ordered: false }
)

覆盖默认写关注

以下对副本集的操作指定了写关注 w: 2，其 wtimeout 为 5000 毫秒。该操作要么在写操作传播到主节点和一个辅助节点后返回，要么在 5 秒后超时。

db.movies.insert(
    { title: "The Revenant", year: 2015 },
    { writeConcern: { w: 2, j: true, wtimeout: 5000 } }
)

WriteResult

当传递单个文档时，insert() 返回一个 WriteResult() 对象。

成功结果

成功后，返回的 WriteResult 对象包含有关插入文档数量的信息：

WriteResult({ "nInserted" : 1 })

写关注错误

如果 insert() 遇到写关注（write concern）错误，结果包括 WriteResult.writeConcernError 字段：

WriteResult({
  "nInserted" : 1,
  "writeConcernError"({
     "code" : 64,
     "errmsg" : "waiting for replication timed out",
     "errInfo" : {
       "wtimeout" : true,
       "writeConcern" : {
         "w" : "majority",
         "wtimeout" : 100,
         "provenance" : "getLastErrorDefaults"
       }
     }
})

与写关注无关的错误

如果 insert() 遇到非写关注错误，结果将包括 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

当传递一组文档时，insert() 返回一个BulkWriteResult()对象。

后退

db.collection.hideIndex

来年

db.collection.insertMany

重要