OPTIONS
翻译或纠错本页面

db.collection.insert()

说明

db.collection.insert()

向集合中插入一条文档记录

The insert() method has the following syntax:

在 2.6 版更改.

db.collection.insert(
   <document or array of documents>,
   {
     writeConcern: <document>,
     ordered: <boolean>
   }
)
Parameter Type Description
document document or array A document or array of documents to insert into the collection.
writeConcern document

Optional. A document expressing the write concern. Omit to use the default write concern. See 安全写入.

2.6 新版功能.

ordered boolean

Optional. If true, perform an ordered insert of the documents in the array, and if an error occurs with one of documents, MongoDB will return without processing the remaining documents in the array. Defaults to false.

2.6 新版功能.

在 2.6 版更改: The insert() returns an object that contains the status of the operation.

返回:单条插入时返回 写入结果 对象。批量插入时返回 批量插入结果 对象。

行为

安全写入

在 2.6 版更改.

The insert() method uses the insert command, which uses the default write concern. To specify a different write concern, include the write concern in the options parameter.

创建集合

如果集合不存在, insert() 方法会创建集合。

_id 字段

如果要插入的文档记录中没有 _id 字段,MongoDB 会在插入前添加 _id 字段并给它一个唯一的 ObjectId 类型的值。大多数驱动层会自动创建 _id 字段并给它一个 ObjectId 类型的值,如果驱动层和应用程序没有创建它, mongod 会创建 _id 字段。

如果文档记录中指定 _id 字段,为避免发生主键重复异常, _id 字段的值必须保证在集合中唯一。

例如

下面这个例子会在 products 集合中插入文档记录。如果集合不存在, insert() 方法会创建集合。

插入一个未指定 _id 字段的文档记录。

在下面这个例子中,传给 insert() 方法的文档记录中,不包含 _id 字段:

db.products.insert( { item: "card", qty: 15 } )

插入时, mongod 会创建 _id 字段并给它一个唯一的 ObjectId 类型的值,插入后的文档记录如下:

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

执行操作时 ObjectId 对象的取值由当前主机和时间决定,所以测试时插入的值会和上面的例子中不同。

插入一个包含 _id 字段的文档记录

在下面的例子中,传给 insert() 方法的文档记录中包含 _id 字段。为避免发生主键重复异常, _id 字段的值必须保证在集合中唯一。

db.products.insert( { _id: 10, item: "box", qty: 20 } )

products 集合中插入下列文档记录:

{ "_id" : 10, "item" : "box", "qty" : 20 }

批量插入

下面的例子演示了批量插入, 给 insert() 方法传入一个由三个文档记录组成一个数组。

数组中的文档记录不需要包含相同的字段。例如,第一个文档记录中包含 _idtype 字段。由于第二第三两个文档记录中没有 _id 字段, mongod 会在插入时给它们添加 _id 字段。

db.products.insert(
   [
     { _id: 11, item: "pencil", qty: 50, type: "no.2" },
     { item: "pen", qty: 20 },
     { item: "eraser", qty: 25 }
   ]
)

本次操作插入如下3个文档记录:

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }

执行一个有序插入

下面例子执行一个有序( ordered )插入,插入4个文档记录。 unordered 无序的插入会在遇到异常时继续执行,有序插入不同,碰到异常时它会直接返回,不会继续插入数组中其余的文档记录。

db.products.insert(
   [
     { _id: 20, item: "lamp", qty: 50, type: "desk" },
     { _id: 21, item: "lamp", qty: 20, type: "floor" },
     { _id: 22, item: "bulk", qty: 100 }
   ],
   { ordered: true }
)

变量默认的写确认级别

在一个副本集中执行操作时,把 write concern 设置成 "w: majority"wtimeout 设置成 5000 毫秒,这样 insert() 方法会在写操作传入副本集的大多数成员或时间超过5秒后返回。

db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: "majority", wtimeout: 5000 } }
)

写入结果

在 2.6 版更改.

传入单条文档记录时, insert() 方法返回 写入结果 对象。

成功时的返回结果

The insert() returns a WriteResult object that contains the status of the operation. Upon success, the WriteResult object contains information on the number of documents inserted:

WriteResult({ "nInserted" : 1 })

写确认异常

如果 insert() 方法遇到一个写确认异常,返回结果中会包含 WriteResult.writeConcernError 字段:

WriteResult({
   "nInserted" : 1,
   "writeConcernError" : {
      "code" : 64,
      "errmsg" : "waiting for replication timed out at shard-a"
   }
})

与写确认无关的异常

insert() 方法遇到一个与写确认无关的异常时,返回结果中会包含 WriteResult.writeError 字段:

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 11000,
      "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_  dup key: { : 1.0 }"
   }
})

批量插入结果

在 2.6 版更改.

传入一个文档记录的数组时, insert() 方法返回 批量插入结果 对象。详情参见 BulkWriteResult()