db.collection.insertOne（）

MongoDB 中文手册

参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.insertOne（）

在本页面

定义
行为举止
例子

定义¶

db.collection.insertOne（）¶

mongo 壳法

此页面记录了mongoshell方法，并且没有引用MongoDB Node.js驱动程序（或任何其他驱动程序）方法。对于相应的MongoDB驱动程序API，请改为参考您特定的 MongoDB驱动程序文档。

3.2版中的新功能。

将文档插入集合中。

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

复制

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

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

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

行为¶

集合创建¶

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

`_id`字段¶

如果文档未指定_id字段，则将在插入之前mongod 添加该_id字段并ObjectId为文档分配唯一性。大多数驱动程序会创建一个ObjectId并插入_id字段，但如果驱动程序或应用程序未mongod创建，则会创建并填充_id。

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

可解释性¶

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

使用insert()代替。

错误处理¶

错误时，db.collection.insertOne()引发a writeError 或writeConcernError异常。

交易¶

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

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

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

重要

在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应代替有效的架构设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）对于您的数据和用例将继续是最佳的。也就是说，在许多情况下，对数据进行适当的建模将最大程度地减少对多文档交易的需求。

有关其他事务使用方面的注意事项（例如运行时限制和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,
   "errInfo" : {
      "wtimeout" : true
   },
   "errmsg" : "waiting for replication timed out"
})

也可以看看

要插入多个文档，请参阅 db.collection.insertMany()

MongoDB 中文手册

db.collection.insertOne（）

定义¶

行为¶

集合创建¶

_id字段¶

可解释性¶

错误处理¶

交易¶

例子¶

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

插入指定_id字段的文档¶

提高写入关注¶

`_id`字段¶

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

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