db.collection.insertOne()

在本页面

• Definition

• Behaviors

• Examples

Definition

• db.collection. insertOne ( )
  • 3.2 版中的新功能。

将文档插入集合中。

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

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

Parameter	Type	Description
document	document	要插入集合中的文档。
writeConcern	document	可选的。表示write concern的文档。省略使用默认的写关注。

返回：	包含以下内容的文档： 如果操作与write concern一起运行，则布尔acknowledged作为true；如果禁用写关注，则为false。	字段insertedId的值为插入文档的_id。

Behaviors

Collection Creation

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

_id Field

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

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

Explainability

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

请改用insert()。

Error Handling

发生错误时，insertOne()会引发writeError或writeConcernError异常。

Examples

插入文档而不指定_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 }

为属于unique index的任何键(例如_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"
})