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

db.collection.insertOne()

在此页面上

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

带驱动程序的 MongoDB

本页面提供 mongosh 方法的相关信息。要查看 MongoDB 驱动程序中的等效方法，请参阅编程语言的相应页面：

C#Java SyncNode.jsPyMongoCC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

定义

db.collection.insertOne()

将单个文档插入集合。

返回：文档包含以下内容：

  • 如果操作使用 写关注来运行，则布尔值 acknowledged 为 true；如果已禁用写关注，则为 false

  • 包含已插入文档的 _id 值的字段 insertedId。

兼容性

此方法可用于以下环境中托管的部署：

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

语法

insertOne() 方法采用以下形式：

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

insertOne() 方法使用以下参数：

Parameter
类型
说明

document

文档

要插入到集合中的文档。

writeConcern

文档

可选。描述写关注的文档。省略以使用默认写关注。.. include:: /includes/extracts/transactions-operations-write-concern.rst

行为

创建集合

如果集合不存在，那么 insertOne() 方法将会创建该集合。

_id 字段

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

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

可解释性

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

Error Handling

如果出错，db.collection.insertOne() 会引发 writeError 或 writeConcernError 异常。

模式验证错误

如果您的集合使用模式验证并将 validationAction 设置为error ，则插入无效文档会引发 MongoServerError 且 db.collection.insertOne() 会失败。

事务

db.collection.insertOne() 可以在分布式事务中使用。

重要

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

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

在事务中创建集合

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

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

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

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

Oplog 条目

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

示例

插入文档而不指定 _id 字段

在下面的示例中，传递给 insertOne() 方法的文档不包含 _id 字段：

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

该操作将返回以下文档：

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

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

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

插入文档并指定 _id 字段

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

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

该操作返回以下内容：

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

为属于唯一索引的任何键插入重复值（例如 _id）会引发异常。下面的例子中尝试插入一个已存在 _id 值的文档：

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

由于 _id: 10 已存在，因此会抛出以下异常：

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
   }
})

增加写关注

给定一个三节点副本集，以下操作指定 w 为 majority，指定 wtimeout 为 100：

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

如果确认花费的时间超过wtimeout限制，则会引发以下异常：

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

提示

另请参阅：

后退

db.collection.insertMany

来年

db.collection.isCapped