createCL - 创建一个新的集合。
db.collectionspace.createCL(<name>,[options])
Collection Space
在指定集合空间下创建集合(Collection),集合是数据库中存放文档记录的逻辑对象,任何一条文档记录必须属于一个且仅属于一个集合。
name
( String, 必填 )
集合名,在同一个集合空间中,集合名必须唯一。
options
( Object, 选填 )
在创建集合时,可以通过options
参数设置集合的其他属性,如指定集合的分区键,是否以压缩的形式插入数据等。可组合使用 options
的如下选项:
ShardingKey
( Object ):分区键。
格式:ShardingKey:{<字段1> : <1|-1>,[<字段2> : <1|-1>, ...]}
ShardingType
( String ):分区方式。默认为 hash 分区。其可选取值如下:
格式:ShardingType:"hash"|"range"
Partition
( Int32 ):分区数。仅当选择 hash 分区时填写,代表了 hash 分区的个数。其值必须是2的幂。范围在[2^3,2^20]。默认为4096。
格式:Partition: <分区数>
ReplSize
( Int32 ):写操作需同步的副本数。默认值为1。其可选取值如下:
格式:ReplSize: <num>
Compressed
( Bool ):标示新集合是否开启数据压缩功能。默认为 true。
格式:Compressed:true|false
CompressionType
( String ):压缩算法类型。默认为 lzw 算法。其可选取值如下:
格式:CompressionType:"snappy"|"lzw"
IsMainCL
( Bool ):标示新集合是否为主分区集合,默认为 false。
格式:IsMainCL:true|false
AutoSplit
( Bool ):标示新集合是否开启自动切分功能,默认为 false。
格式:AutoSplit:true|false
Group
( String ):指定新集合将被创建到哪个复制组。
格式:Group:<group name>
AutoIndexId
( Bool ):标示新集合是否自动使用_id字段创建名字为"$id"的唯一索引,默认为 true。
格式:AutoIndexId:true|false
EnsureShardingIndex
( Bool ):标示集合是否自动使用ShardingKey包含的字段创建名字为"$shard"的索引,默认为true。
格式:EnsureShardingIndex:true|false
StrictDataMode
( Bool ):标示对该集合的操作是否开启严格数据类型模式,默认为false(不开启)。严格数据模式的开启标示对数值操作存在以下限制:
格式:StrictDataMode:true|false
AutoIncrement
( Object ):自增字段
格式:AutoIncrement:{Field: <字段>, ...}
或 AutoIncrement:[ {Field: <字段1>, ...}, {Field: <字段2>, ...}, ... ]
例子:AutoIncrement: { Field: "userID", Generated: "always" }
LobShardingKeyFormat
( String ):指定大对象生成主表切分键键值的格式。目前支持将大对象ID中的时间属性转换成如下字符串形式:
格式:LobShardingKeyFormat:"YYYYMMDD"|"YYYYMM"|"YYYY"
Note:
集合名限制请参考限制
当参数
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及以上版本。
在集合空间 sample 下创建集合 employee,不指定分区键。
> db.sample.createCL("employee") localhost:11810.sample.employee Takes 0.120450s.
在集合空间 sample 下创建集合 employee。该集合若需要切分数据到其它复制组,将 使用 age 字段进行 hash 切分;该集合默认开启了数据压缩功能,使用默认的 lzw 算法压缩数据;写操作作用于该集合时,只需写入主节点即可返回。
> db.sample.createCL( "employee",{ ShardingKey:{ age: 1 }, ShardingType: "hash", Partition: 4096, ReplSize: 1 } ) localhost:11810.sample.employee Takes 0.110319s.
在集合空间 sample 下创建集合 employee,开启严格数据类型模式。
> db.sample.createCL("employee", {StrictDataMode: true}) localhost:11810.sample.employee Takes 0.120450s.
在主表下使用大对象
> db.sample.createCL("maincl", { LobShardingKeyFormat:"YYYYMMDD", ShardingKey:{ date:1 }, IsMainCL:true, ShardingType:"range" } ) localhost:11810.sample.maincl Takes 0.058532s. > db.sample.createCL("subcl") localhost:11810.sample.subcl Takes 0.294612s. > db.sample.maincl.attachCL( "sample.subcl", { LowBound: { date: "20190701" }, UpBound: { date: "20190801" } } ) Takes 0.008561s.
> Timestamp() Timestamp("2019-07-23-18.04.07.539050") > db.sample.maincl.putLob('/opt/data/test.dat') 00005d36dbee370002de8080 Takes 0.246062s.
> db.sample.maincl.createLobID("2019-07-23-18.04.07") 00005d36db97360002de8081 Takes 0.108365s. > db.sample.maincl.putLob('/opt/data/test.dat', '00005d36db97360002de8081') 00005d36db97360002de8081 Takes 0.002216s.
创建主分区集合(对应主表)或是子分区集合(对应子表)之后,在使用主分区集合/子分区集合时需要注意一些特殊情况:
验证从主分区集合和子分区集合中执行写操作时,AutoIncrement 属性的对应情况。
创建主分区集合 masterCL,自增字段为:masterID。
> db.sample.createCL("masterCL",{ IsMainCL: true, ShardingKey: { a: 1 }, ShardingType: "range", AutoIncrement: { Field: "masterID" } }) localhost:11810.sample.masterCL Takes 0.002450s.
创建子分区集合 slaveCL,自增字段为:slaveID。
> db.sample.createCL("slaveCL",{ ShardingKey: { b: 1 }, ShardingType: "hash", Partition: 1024, AutoIncrement: { Field: "slaveID" }}) localhost:11810.sample.slaveCL Takes 0.263536s.
将子分区集合附加到主分区集合中。
> db.sample.masterCL.attachCL( "sample.slaveCL", { LowBound: { a: 0 }, UpBound: { a: 100 } } ) Takes 0.002743s.
从主分区集合 masterCL 中插入数据 {"a":1} 时,AutoIncrement 会沿用主分区集合对应的属性,所以数据会带有 masterID 信息 。从子分区集合 slaveCL 中插入数据 {"a":2} 时,AutoIncrement 会沿用子分区集合的属性,所以数据会带有 slaveID 信息。
> db.sample.masterCL.insert({"a":1}) //主分区集合插入数据 Takes 0.001877s. > db.sample.slaveCL.insert({"a":2}) //子分区集合插入数据 Takes 0.001238s. > db.sample.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 等,子分区集合会使用自己的属性而不是沿用主分区集合的对应属性。