文档中心

SequoiaDB 简介

快速入门

安装部署

数据库实例

分布式引擎

SAC管控中心

SequoiaPerf性能分析工具

参考手册

常见问题及解答(FAQ)

版本信息

insert()

名称

insert - 将单条或者批量记录插入当前集合

语法

db.collectionspace.collection.insert(<doc|docs>,[flag])

db.collectionspace.collection.insert(<doc|docs>,[options])

类别

SdbCollection

描述

该函数用于将单条或者批量记录插入当前集合。

参数

  • doc|docs ( Object|Object of Array必填 )

    单条或者批量记录。

  • flag ( Int选填 )

    插入标志位,用于控制插入操作的行为及结果。其默认值为 0。可单独使用或者通过“位与”的方式使用如下选项来控制插入操作的行为及结果:

    • SDB_INSERT_RETURN_ID:表示插入成功后返回记录中“_id”字段的内容。
    • SDB_INSERT_CONTONDUP:默认情况下,当发生索引键冲突时,插入操作将失败并且终止。设置该选项后,当发生索引键冲突时,跳过该条记录并继续插入其他记录。
    • SDB_INSERT_REPLACEONDUP:默认情况下,当发生索引键冲突时,插入操作将失败并且终止。设置该选项后,当发生索引键冲突时,将已存在的记录更新为待插入的新记录,并继续插入其他记录。
  • options ( Object选填 )

    插入选项,用于控制插入操作的行为及结果。参数 options 等同于参数 flag,其属性选项如下:

    • ReturnOID ( Bool选填 ):等同于参数 flag 中的 SDB_INSERT_RETURN_ID 选项。
    • ContOnDup ( Bool选填 ):等同于参数 flag 中的 SDB_INSERT_CONTONDUP 选项。
    • ReplaceOnDup ( Bool选填 ):等同于参数 flag 中的 SDB_INSERT_REPLACEONDUP 选项。

Note:

  • 当插入的记录不包含 “_id” 字段时,SequoiaDB 会自动为记录添加一个 “_id” 字段来唯一标识该记录。

  • 参数 flag 中的 SDB_INSERT_CONTONDUP 和 SDB_INSERT_REPLACEONDUP 选项不能同时组合使用。使用参数 options 时的情况与使用参数 flag 的一致。

返回值

函数执行成功时,将返回一个 BSONObj 类型的对象,通过该对象获取成功插入的记录数信息,字段说明如下:

字段名 类型 描述
InsertedNum int64 成功插入的记录数,不包含替代和忽略的记录
DuplicatedNum int64 因重复键冲突被忽略或替代的记录数
LastGenerateID int64 自增字段的值(仅在集合包含自增字段时显示),返回情况如下:
- 当插入单条记录时,返回该记录所对应的自增字段值
- 当插入多条记录时,仅返回第一条记录对应的自增字段值
- 当存在多个自增字段时,插入单条记录,仅返回所有自增字段中的最大值
- 当存在多个自增字段时,插入多条记录,仅返回第一条记录所对应的最大自增字段值
_id oid 返回插入的记录中 _id 字段所包含的内容(仅开启 flag 参数的SDB_INSERT_RETURN_ID 选项或 options 参数的 ReturnOID 选项时显示 )

函数执行失败时,将抛异常并输出错误信息。

错误

insert()函数常见异常如下:

错误码 错误类型 描述 解决方法
-6 SDB_INVALIDARG 参数错误。 查看参数是否填写正确。
-23 SDB_DMS_NOTEXIST 集合不存在。 检查集合是否存在。
-34 SDB_DMS_CS_NOTEXIST 集合空间不存在。 检查集合空间是否存在。
-38 SDB_IXM_DUP_KEY 索引键已存在。 检查插入的记录的索引键是否已经存在。

当异常抛出时,可以通过 getLastErrMsg() 获取错误信息或通过 getLastError() 获取错误码。更多错误处理可以参考常见错误处理指南

版本

v1.0 及以上版本。

示例

  • 不指定 _id 字段,插入一条记录

    > db.sample.employee.insert( { name: "Tom", age: 20 } )
  • 插入一条带有 _id 字段的记录

    > db.sample.employee.insert( {_id: 10, age: 20 } )
  • 插入多条记录,如下操作会在集合 sample.employee 中插入两条记录

    > db.sample.employee.insert( [ { _id: 20, name: "Mike", age: 15 }, { name: "John", age: 25, phone: 123 } ] )
  • 插入拥有重复 _id 键的多条记录,如下操作将会在集合 sample.employee 中插入两条记录

    > db.sample.employee.insert( [ { _id: 1, a: 1 }, { _id: 1, b:2 }, { _id: 3, c: 3 } ],  SDB_INSERT_CONTONDUP )
    > db.sample.employee.find()
    {
      "_id": 1,
      "a": 1,
    }
    {
      "_id": 3,
      "c": 3
    }
  • 插入记录,并以 json 对象的方式返回结果

    > db.sample.employee.insert({a:1}, {ReturnOID:true})
    {
        "_id": {
            "$oid": "5becec3d6404b9295a63caca"
        }
        "InsertedNum": 1,
        "DuplicatedNum": 0
    }
    >
    > db.sample.employee.insert([{a:1}, {b:1}], {ReturnOID:true})
    {
        "_id": [
            {
                "$oid": "5bececdf6404b9295a63cacb"
            },
            {
                "$oid": "5bececdf6404b9295a63cacc"
            }
        ]
        "InsertedNum": 2,
        "DuplicatedNum": 0
    }
    > db.sample.employee.createAutoIncrement({ Field: "ID" })
    > db.sample.employee.insert({ a: 1 })
    {
        "InsertedNum": 1,
        "DuplicatedNum": 0,
        "LastGenerateID": 1
    }
回到顶部