db.collection.insertOne()
MongoDB与驱动程序
本页文档了一个mongosh方法。要查看特定编程语言的相应驱动程序中的等效方法，请参阅相应页面的内容
定义
db.collection.insertOne()将单个文档插入到集合中。
返回: 包含以下内容的文档 一个布尔值
acknowledged，如果操作在具有write-concern的条件下运行则为true，如果禁用了写关注则为false。写关注一个字段
insertedId，包含插入文档的_id值。
兼容性
此方法在以下环境中提供
MongoDB Atlas：MongoDB在云中的托管服务
注意
此命令支持所有MongoDB Atlas集群。有关Atlas对所有命令的支持信息，请参阅不受支持的命令。
MongoDB Enterprise：基于订阅、自行管理的MongoDB版本
MongoDB Community：源代码可用的、免费使用且可自行管理的MongoDB版本
语法
insertOne() 方法具有以下形式
db.collection.insertOne( <document>, { writeConcern: <document> } )
insertOne() 方法接受以下参数
参数 | 类型 | 描述 |
|---|---|---|
document | document | 要插入到集合中的文档。 |
writeConcern | document | 可选。表示 write concern 的文档。省略则使用默认的write concern。.. include:: /includes/extracts/transactions-operations-write-concern.rst |
行为
集合创建
如果集合不存在，则 insertOne() 方法将创建该集合。
_id 字段
如果文档未指定 _id 字段，则 mongod 将添加 _id 字段并为文档分配一个唯一的 ObjectId()，然后在插入之前。大多数驱动程序都会创建一个 ObjectId 并插入 _id 字段，但如果驱动程序或应用程序没有做，则 mongod 将创建并填充 _id。
如果文档包含 _id 字段，则该 _id 值必须在集合内是唯一的，以避免重复键错误。
可解释性
错误处理
当发生错误时，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" } } })