db.collection.insertOne()¶

Collection Creation集合创作¶

If the collection does not exist, then the insertOne() method creates the collection.如果集合不存在，那么insertOne()方法将创建集合。

_id Field字段¶

If the document does not specify an _id field, then mongod will add the _id field and assign a unique ObjectId for the document before inserting. 如果文档未指定_id字段，则mongod将添加_id字段，并在插入之前为文档指定唯一的ObjectId。Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.大多数驱动程序创建ObjectId并插入_id字段，但如果驱动程序或应用程序不创建并填充_id，mongod将创建并填充。

If the document contains an _id field, the _id value must be unique within the collection to avoid duplicate key error.如果文档包含_id字段，_id值在集合中必须是唯一的，以避免重复键错误。

Explainability解释能力¶

insertOne() is not compatible with db.collection.explain().与db.collection.explain()不兼容。

Use insert() instead.请改用insert()。

Error Handling错误处理¶

On error, db.collection.insertOne() throws either a writeError or writeConcernError exception.出现错误时，db.collection.insertOne()会引发writeError或writeConcernError异常。

Transactions事务¶

db.collection.insertOne() can be used inside multi-document transactions.可以在多文档事务中使用。

Insert a Document without Specifying an _id Field在不指定_id字段的情况下插入文档¶

In the following example, the document passed to the insertOne() method does not contain the _id field:在以下示例中，传递给insertOne()方法的文档不包含_id字段：

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

The operation returns the following document:该操作将返回以下文档：

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

Because the documents did not include _id, mongod creates and adds the _id field and assigns it a unique ObjectId value.由于文档不包含_id，mongod创建并添加_id字段，并为其分配唯一的ObjectId值。

The ObjectId values are specific to the machine and time when the operation is run. ObjectId值特定于机器和运行操作的时间。As such, your values may differ from those in the example.例如，你的价值观可能与你的例子中的不同。

Insert a Document Specifying an _id Field插入指定_id字段的文档¶

In the following example, the document passed to the insertOne() method includes the _id field. 在下面的示例中，传递给insertOne()方法的文档包括_id字段。The value of _id must be unique within the collection to avoid duplicate key error._id的值在集合中必须是唯一的，以避免重复密钥错误。

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

The operation returns the following:该操作返回以下内容：

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

Inserting an duplicate value for any key that is part of a unique index, such as _id, throws an exception. 为属于唯一索引的任何键（如_id）插入重复值会引发异常。The following attempts to insert a document with a _id value that already exists:以下尝试插入具有已存在的_id值的文档：

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

Since _id: 10 already exists, the following exception is thrown:由于_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
   }
})

Increase Write Concern增加写入关注度¶

Given a three member replica set, the following operation specifies a w of majority, wtimeout of 100:给定一个由三个成员组成的副本集，以下操作指定w的多数，wtimeout为100：

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

If the acknowledgement takes longer than the wtimeout limit, the following exception is thrown:如果确认时间超过wtimeout限制，则会引发以下异常：

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