文档

关于 SequoiaDB

快速入门

安装

基本操作

数据模型

SQL引擎

FileSystem引擎

S3引擎

系统架构

数据库管理

连接器

驱动

参考手册

SequoiaDB Shell方法

概述

Global

Sdb

SecureSdb

SdbCS

SdbCollection

SdbCursor

SdbQuery

SdbReplicaGroup

SdbNode

SdbDomain

Oma

File

FileContent

Cmd

Remote

Hash

IniFile

Sdbtool

Ssh

System

辅助类型对象

特殊类型对象

操作符

SQL语法

SQL to SequoiaDB 映射表

限制

错误码

故障排除

SAC 管控中心

Web服务

版本信息

createCL()

名称

createCL - 创建一个新的集合。

语法

db.collectionspace.createCL(<name>,[options])

类别

Collection Space

描述

在指定集合空间下创建集合(Collection),集合是数据库中存放文档记录的逻辑对象,任何一条文档记录必须属于一个且仅属于一个集合。

参数

  • name ( String必填 )

    集合名,在同一个集合空间中,集合名必须唯一。

  • options ( Object选填 )

    在创建集合时,可以通过options参数设置集合的其他属性,如指定集合的分区键,是否以压缩的形式插入数据等。可组合使用 options 的如下选项:

    1. ShardingKey ( Object ):分区键。

      格式:ShardingKey:{<字段1> : <1|-1>,[<字段2> : <1|-1>, ...]}

    2. ShardingType ( String ):分区方式。默认为 hash 分区。其可选取值如下:

      • "hash":hash 分区。
      • "range":范围分区。

      格式:ShardingType:"hash"|"range"

    3. Partition ( Int32 ):分区数。仅当选择 hash 分区时填写,代表了 hash 分区的个数。其值必须是2的幂。范围在[2^3,2^20]。默认为4096。

      格式:Partition: <分区数>

    4. ReplSize ( Int32 ):写操作需同步的副本数。默认值为1。其可选取值如下:

      • -1:表示写请求需同步到该复制组若干活跃的节点之后,数据库写操作才返回应答给客户端。
      • 0:表示写请求需同步到该复制组的所有节点之后,数据库写操作才返回应答给客户端。
      • 1 - 7:表示写请求需同步到该复制组指定数量个节点之后,数据库写操作才返回应答给客户端。

      格式:ReplSize: <num>

    5. Compressed ( Bool ):标示新集合是否开启数据压缩功能。默认为 true。

      格式:Compressed:true|false

    6. CompressionType ( String ):压缩算法类型。默认为 lzw 算法。其可选取值如下:

      • "snappy":使用 snappy 算法压缩。
      • "lzw":使用 lzw 算法压缩。

      格式:CompressionType:"snappy"|"lzw"

    7. IsMainCL ( Bool ):标示新集合是否为主分区集合,默认为 false。

      格式:IsMainCL:true|false

    8. AutoSplit ( Bool ):标示新集合是否开启自动切分功能,默认为 false。

      格式:AutoSplit:true|false

    9. Group ( String ):指定新集合将被创建到哪个复制组。

      格式:Group:<group name>

    10. AutoIndexId ( Bool ):标示新集合是否自动使用_id字段创建名字为"$id"的唯一索引,默认为 true。

      格式:AutoIndexId:true|false

    11. EnsureShardingIndex ( Bool ):标示集合是否自动使用ShardingKey包含的字段创建名字为"$shard"的索引,默认为true。

      格式:EnsureShardingIndex:true|false

    12. StrictDataMode ( Bool ):标示对该集合的操作是否开启严格数据类型模式,默认为false(不开启)。严格数据模式的开启标示对数值操作存在以下限制:

      • 运算过程不改数据类型;
      • 数值运算出现溢出时直接报错,错误码SDB_VALUE_OVERFLOW;

      格式:StrictDataMode:true|false

    13. AutoIncrement ( Object ):自增字段

      格式:AutoIncrement:{Field: <字段>, ...}AutoIncrement:[ {Field: <字段1>, ...}, {Field: <字段2>, ...}, ... ]

      例子:AutoIncrement: { Field: "userID", Generated: "always" }

    14. LobShardingKeyFormat ( String ):指定大对象生成主表切分键键值的格式。目前支持将大对象ID中的时间属性转换成如下字符串形式:

      • "YYYYMMDD":将大对象ID的时间属性转换为年月日的字符串形式,如"20190701"。
      • "YYYYMM":将大对象ID的时间属性转换为年月的字符串形式,如"201907"。
      • "YYYY":将大对象ID的时间属性转换为年的字符串形式,如"2019"。

      格式:LobShardingKeyFormat:"YYYYMMDD"|"YYYYMM"|"YYYY"

    注意:

    • 参数 name 的值不能是空串、含点(.)或者美元符号($),并且长度不能超过127B,否则操作失败。

    • 当参数 options 内设置了多个参数时,需用英文半角的逗号","将各参数的取值隔开。

    • 创建集合空间时,可以指定所属的数据域。创建集合时,使用 Group 参数,指定的复制组必须在域内;不使用 Group 参数,集合将被创建在域的任意一个复制组上。

    • 创建集合的 AutoSplit 参数比数据域的 AutoSplit 属性优先级更高。

    • AutoSplit 不能与 Group 参数同时使用。

    • AutoSplit 必须配合散列分区使用。

    • 压缩算法选择策略:snappy 压缩算法是以单条记录为单位进行压缩,记录内部的数据重复度直接影响到压缩率。因此,当记录内部数据重复度较高,如每条记录的字段名、字段值相似,使用 snappy 算法可获得良好的压缩性能。如果记录内部数据重复度很低,但记录间具有更高的相似性,如不同记录之间有相同的字段名,相近的字段值等,则使用 lzw 算法更优。

    • LobShardingKeyFormat 只能在主表中使用,同时要求切分键只能有一个切分字段。

返回值

成功:返回一个新的SdbCollection对象。

失败:抛出异常。

错误

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

错误码 错误类型 描述 解决方法
-2 SDB_OOM 无可用内存。 检查物理内存及虚拟内存的情况。
-6 SDB_INVALIDARG 参数错误。 查看参数是否填写正确。
-22 SDB_DMS_EXIST 集合已存在。 检查集合是否存在。
-34 SDB_DMS_CS_NOTEXIST 集合空间不存在。 检查集合空间是否存在。
-318 SDB_VALUE_OVERFLOW 数值运算出现溢出。 检查运算过程是否存在溢出情况。

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

版本

v1.0及以上版本。

例子

  1. 在集合空间 foo 下创建集合 bar,不指定分区键。

    > db.foo.createCL( "bar" )
    localhost:11810.foo.bar
    Takes 0.120450s.
  2. 在集合空间 foo 下创建集合 bar。该集合若需要切分数据到其它复制组,将 使用 age 字段进行 hash 切分;该集合默认开启了数据压缩功能,使用默认的 lzw 算法压缩数据;写操作作用于该集合时,只需写入主节点即可返回。

    > db.foo.createCL( "bar",{ ShardingKey:{ age: 1 }, ShardingType: "hash", Partition: 4096, ReplSize: 1 } )
    localhost:11810.foo.bar
    Takes 0.110319s.
  3. 在集合空间 foo 下创建集合 bar,开启严格数据类型模式。

    > db.foo.createCL( "bar", { StrictDataMode: true } )
    localhost:11810.foo.bar
    Takes 0.120450s.
  4. 在主表下使用大对象

    • 在集合空间 foo 下创建支持大对象的主集合 maincl,同时关联子表 subcl。
    > db.foo.createCL("maincl", { LobShardingKeyFormat:"YYYYMMDD", ShardingKey:{ date:1 }, IsMainCL:true, ShardingType:"range" } )
    localhost:11810.foo.maincl
    Takes 0.058532s.
    > db.foo.createCL("subcl")
    localhost:11810.foo.subcl
    Takes 0.294612s.
    > db.foo.maincl.attachCL( "foo.subcl", { LowBound: { date: "20190701" }, UpBound: { date: "20190801" } } )
    Takes 0.008561s.
    • 在[20190701, 20190801)之间创建的大对象数据则会落在集合 foo.subcl 中
    > Timestamp()
    Timestamp("2019-07-23-18.04.07.539050")
    > db.foo.maincl.putLob('/opt/data/test.dat')
    00005d36dbee370002de8080
    Takes 0.246062s.
    • 也可以指定大对象ID的时间属性
    > db.foo.maincl.createLobID("2019-07-23-18.04.07")
    00005d36db97360002de8081
    Takes 0.108365s.
    > db.foo.maincl.putLob('/opt/data/test.dat', '00005d36db97360002de8081')
    00005d36db97360002de8081
    Takes 0.002216s.

注意事项

创建主分区集合(对应主表)或是子分区集合(对应子表)之后,在使用主分区集合/子分区集合时需要注意一些特殊情况:

  1. 从主分区集合中执行写操作时,replSize、AutoIncrement 会沿用主分区集合对应的属性。
  2. 从子分区集合中执行写操作时,replSize、AutoIncrement 会沿用子分区集合对应的属性。

例子

验证从主分区集合和子分区集合中执行写操作时,AutoIncrement 属性的对应情况。

创建主分区集合 masterCL,自增字段为:masterID。

    > db.foo.createCL("masterCL",{ IsMainCL: true, ShardingKey: { a: 1 }, ShardingType: "range", AutoIncrement: { Field: "masterID" } })
    localhost:11810.foo.masterCL
    Takes 0.002450s.

创建子分区集合 slaveCL,自增字段为:slaveID。

    > db.foo.createCL("slaveCL",{ ShardingKey: { b: 1 }, ShardingType: "hash", Partition: 1024, AutoIncrement: { Field: "slaveID" }})
    localhost:11810.foo.slaveCL
    Takes 0.263536s.

将子分区集合附加到主分区集合中。

    > db.foo.masterCL.attachCL( "foo.slaveCL", { LowBound: { a: 0 }, UpBound: { a: 100 } } )
    Takes 0.002743s.

从主分区集合 masterCL 中插入数据 {"a":1} 时,AutoIncrement 会沿用主分区集合对应的属性,所以数据会带有 masterID 信息 。从子分区集合 slaveCL 中插入数据 {"a":2} 时,AutoIncrement 会沿用子分区集合的属性,所以数据会带有 slaveID 信息。

    > db.foo.masterCL.insert({"a":1}) //主分区集合插入数据
    Takes 0.001877s.
    > db.foo.slaveCL.insert({"a":2}) //子分区集合插入数据
    Takes 0.001238s.
    > db.foo.masterCL.find() //查看结果
    {
      "_id": {
        "$oid": "5d42b40d2d7dfa6391e3cbd9"
      },
      "a": 1,
      "masterID": 1
    }
    {
      "_id": {
        "$oid": "5d42b4342d7dfa6391e3cbda"
      },
      "a": 2,
      "slaveID": 1
    }
    Return 2 row(s).
    Takes 0.001234s.
    > 

集合的其他属性,如 ShardingKey、Compressed、AutoIndexId 等,子分区集合会使用自己的属性而不是沿用主分区集合的对应属性。

回到顶部