Docs 菜单
Docs 主页
/
MongoDB Manual
/ / /

insert

在此页面上

  • 定义
  • 兼容性
  • 语法
  • 命令字段
  • 行为
  • 示例
  • 输出
insert

insert命令会插入一个或多个文档,并返回一个包含所有插入状态的文档。MongoDB 驱动程序提供的插入方法会在内部使用此命令。

提示

mongosh中,该命令还可以通过 db.collection.insertOne()db.collection.insertMany()辅助方法运行。

辅助方法对 mongosh 用户来说很方便,但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段,请使用数据库命令。

返回:包含操作状态的文档。有关详细信息,请参阅输出

此命令可用于以下环境中托管的部署:

  • MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关所有命令的信息,请参阅不支持的命令

该命令具有以下语法:

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

可选。

指定时间限制(以毫秒为单位)。如果您未指定 maxTimeMS 值,操作将不会超时。如果值为 0 ,则显式指定默认无限制行为。

MongoDB 使用与 db.killOp() 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。

writeConcern
文档

可选。用于表达 insert 命令写关注的文档。省略以使用默认的写关注。

如果是在事务中运行,则请勿显式设置此操作的写关注。要将写关注与事务一起使用,请参阅事务和写关注。

bypassDocumentValidation
布尔
可选。启用 insert 可在操作过程中绕过文档验证。这样就可以插入不符合验证要求的文档。
comment
any

可选。用户提供的待附加到该命令的注释。设置后,该注释将与该命令的记录一起出现在以下位置:

注释可以是任何有效的 BSON 类型(字符串、整型、对象、数组等)。

所有 documents 数组元素的总大小必须小于或等于最大 BSON 文档大小

documents 数组中的文档总数必须小于或等于最大批量大小。

insert 命令可为 bypassDocumentValidation 选项添加支持,以便在附带验证规则的集合中插入或更新文档时绕过文档验证

insert 可以在分布式事务中使用。

重要

在大多数情况下,与单文档写入操作相比,分布式事务会产生更高的性能成本,并且分布式事务的可用性不应取代有效的模式设计。在许多情况下,非规范化数据模型(嵌入式文档和数组)仍然是数据和使用案例的最佳选择。换言之,对于许多场景,适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项(如运行时间限制和 oplog 大小限制),另请参阅生产注意事项

如果事务不是跨分片写事务,则可以在分布式事务中创建集合和索引。

如果在事务中对不存在的集合指定插入操作,则 MongoDB 会隐式创建该集合。

提示

另请参阅:

如果是在事务中运行,则请勿显式设置此操作的写关注。要将写关注与事务一起使用,请参阅事务和写关注。

即使在插入过程中遇到服务器错误,某些文档也可能已插入。

插入成功后,系统会返回 insert.n,即已插入集合的文档数。如果插入操作因副本集状态更改而中断,系统可能会继续插入文档。因此,insert.n 报告的文档可能少于实际插入的文档。

将文档插入到 users 集合中:

db.runCommand(
{
insert: "users",
documents: [ { _id: 1, user: "abc123", status: "A" } ]
}
)

返回的文档会显示该命令已成功插入文档。请参阅输出以了解详情。

{ "ok" : 1, "n" : 1 }

将三个文档插入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 }

如果将 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.ok

命令的状态。

insert.n

插入的文档数量。

insert.writeErrors

包含插入操作过程中遇到的任何错误信息的文档数组。writeErrors 数组包含每个出错插入操作的错误文档。

每个错误文档都包含以下字段:

insert.writeErrors.index

一个整数,可用于标识documents数组中的文档,而该数组会使用从零开始的索引。

insert.writeErrors.code

标识错误的整数值。

insert.writeErrors.errmsg

错误描述。

insert.writeConcernError

描述与写关注(write concern)相关的错误的文档。

在版本7.1中进行了更改: 在insert }mongos 上执行 时,即使出现一个或多个写入错误,也始终会报告写关注错误。

在以前的版本中,发生写入错误可能会导致insert不报告写关注(write concern)错误。

writeConcernError文档包含以下字段:

insert.writeConcernError.code

一个整数值,用于标识写关注错误原因。

insert.writeConcernError.errmsg

写关注错误原因的描述。

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 }"
}
]
}

后退

getmore