insert
定义
insert
insert
命令会插入一个或多个文档,并返回一个包含所有插入状态的文档。MongoDB 驱动程序提供的插入方法会在内部使用此命令。提示
在
mongosh
中,该命令还可以通过db.collection.insertOne()
和db.collection.insertMany()
辅助方法运行。辅助方法对
mongosh
用户来说很方便,但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段,请使用数据库命令。返回: 包含操作状态的文档。有关详细信息,请参阅输出。
兼容性
此命令可用于以下环境中托管的部署:
MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务
注意
所有 MongoDB Atlas 集群都支持此命令。有关所有命令的信息,请参阅不支持的命令。
MongoDB Enterprise:基于订阅、自我管理的 MongoDB 版本
MongoDB Community:源代码可用、免费使用且可自行管理的 MongoDB 版本
语法
该命令具有以下语法:
db.runCommand( { insert: <collection>, documents: [ <document>, <document>, <document>, ... ], ordered: <boolean>, maxTimeMS: <integer>, writeConcern: { <write concern> }, bypassDocumentValidation: <boolean>, comment: <any> } )
命令字段
该命令接受以下字段:
字段 | 类型 | 说明 |
---|---|---|
insert | 字符串 | 目标集合的名称。 |
documents | 阵列 | 要插入到已命名集合中的一个或多个文档的数组。 |
ordered | 布尔 | 可选。 如果为 true ,则当插入文档失败时,返回而不插入inserts 数组中列出的任何剩余文档。如果是false ,那么当插入一个文档失败时,继续插入剩余的文档。默认为true 。 |
maxTimeMS | non-negative integer | 可选。 指定时间限制(以毫秒为单位)。如果您未指定 MongoDB 使用与 |
writeConcern | 文档 | |
bypassDocumentValidation | 布尔 | 可选。启用 insert 可在操作过程中绕过文档验证。这样就可以插入不符合验证要求的文档。 |
comment | any | 可选。用户提供的待附加到该命令的注释。设置后,该注释将与该命令的记录一起出现在以下位置:
注释可以是任何有效的 BSON 类型(字符串、整型、对象、数组等)。 |
行为
大小限制
所有 documents
数组元素的总大小必须小于或等于最大 BSON 文档大小。
documents
数组中的文档总数必须小于或等于最大批量大小。
文档验证
insert
命令可为 bypassDocumentValidation
选项添加支持,以便在附带验证规则的集合中插入或更新文档时绕过文档验证。
事务
重要
在大多数情况下,与单文档写入操作相比,分布式事务会产生更高的性能成本,并且分布式事务的可用性不应取代有效的模式设计。在许多情况下,非规范化数据模型(嵌入式文档和数组)仍然是数据和使用案例的最佳选择。换言之,对于许多场景,适当的数据建模将最大限度地减少对分布式事务的需求。
有关其他事务使用注意事项(如运行时间限制和 oplog 大小限制),另请参阅生产注意事项。
在事务中创建集合
如果事务不是跨分片写事务,则可以在分布式事务中创建集合和索引。
如果在事务中对不存在的集合指定插入操作,则 MongoDB 会隐式创建该集合。
写关注和事务
如果是在事务中运行,则请勿显式设置此操作的写关注。要将写关注与事务一起使用,请参阅事务和写关注。
插入不准确
即使在插入过程中遇到服务器错误,某些文档也可能已插入。
插入成功后,系统会返回 insert.n
,即已插入集合的文档数。如果插入操作因副本集状态更改而中断,系统可能会继续插入文档。因此,insert.n
报告的文档可能少于实际插入的文档。
示例
插入单一文档
将文档插入到 users
集合中:
db.runCommand( { insert: "users", documents: [ { _id: 1, user: "abc123", status: "A" } ] } )
返回的文档会显示该命令已成功插入文档。请参阅输出以了解详情。
{ "ok" : 1, "n" : 1 }
Bulk Insert
将三个文档插入users
集合中:
db.runCommand( { insert: "users", documents: [ { _id: 2, user: "ijk123", status: "A" }, { _id: 3, user: "xyz123", status: "P" }, { _id: 4, user: "mop123", status: "P" } ], ordered: false, writeConcern: { w: "majority", wtimeout: 5000 } } )
返回的文档会显示该命令已成功插入这三个文档。请参阅输出以了解详情。
{ "ok" : 1, "n" : 3 }
结合使用插入与 bypassDocumentValidation
如果将 schema validation validationActions 设为 error
,则插入到集合的文档会因违反模式验证规则而返回错误。要插入可能违反这些规则的文档,请设置 bypassDocumentValidation: true
。
使用 status
字段上的验证规则创建 user
集合。
以下验证规则将验证状态必须为“Unknown”或“Incomplete”:
db.createCollection("users", { validator: { status: { $in: [ "Unknown", "Incomplete" ] } } })
试图插入违反验证规则的文档:
db.runCommand({ insert: "users", documents: [ {user: "123", status: "Active" } ] })
插入返回写入错误消息:
{ n: 0, writeErrors: [ { index: 0, code: 121, errInfo: { failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'), details: { operatorName: '$in', specifiedAs: { status: { '$in': [Array] } }, reason: 'no matching value found in array', consideredValue: 'Active' } }, errmsg: 'Document failed validation' } ], ok: 1 }
设置bypassDocumentValidation : true
并重新运行插入操作:
db.runCommand({ insert: "users", documents: [ {user: "123", status: "Active" } ], bypassDocumentValidation: true })
操作成功。
要检查是否有违反模式验证规则的文档,请使用 validate
命令。
输出
返回的文档包含以下字段的子集:
insert.writeErrors
包含插入操作过程中遇到的任何错误信息的文档数组。
writeErrors
数组包含每个出错插入操作的错误文档。每个错误文档都包含以下字段:
insert.writeConcernError
描述与写关注(write concern)相关的错误的文档。
在版本7.1中进行了更改: 在
insert
}mongos
上执行 时,即使出现一个或多个写入错误,也始终会报告写关注错误。在以前的版本中,发生写入错误可能会导致
insert
不报告写关注(write concern)错误。writeConcernError
文档包含以下字段:insert.writeConcernError.errInfo.writeConcern
用于相应操作的写关注对象。有关写关注对象字段的信息,请参阅写关注规范。
写关注对象还可能包含以下字段,指示写关注的来源:
insert.writeConcernError.errInfo.writeConcern.provenance
一个表示写关注来源(称为写关注
provenance
)的字符串值。下表显示该字段的可能值及其有效位数:来源说明clientSupplied
应用程序中指定了写关注。customDefault
写入关注源自自定义的默认值。请参阅setDefaultRWConcern
。getLastErrorDefaults
写关注源自副本集的settings.getLastErrorDefaults
字段。implicitDefault
在没有所有其他写入关注规范的情况下,写入关注源自服务器。
以下是成功 insert
单个文档后返回的文档示例:
{ ok: 1, n: 1 }
在以下示例中,系统会为两个文档的 insert
返回一个示例文档;其中,这两个文档已成功插入一个文档,但在处理另一文档时出现错误:
{ "ok" : 1, "n" : 1, "writeErrors" : [ { "index" : 1, "code" : 11000, "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_ dup key: { : 1.0 }" } ] }