写点什么

【深入理解 TcaplusDB 技术】详细介绍 TDR 表中 Tcaplus 的相关属性

作者:数据人er
  • 2022 年 5 月 16 日
  • 本文字数:7520 字

    阅读完需:约 25 分钟

【深入理解TcaplusDB技术】详细介绍TDR 表中Tcaplus的相关属性

【深入理解 TcaplusDB 技术】详细介绍 TDR 表中 Tcaplus 的相关属性

主键 primarykey

primarykey 属性指明此元素对应数据库表的主键,其取值为以当前元素为父元素的特定子元数据成员名串,如果有多个成员组成表的主键,则成员名之间用逗号(',')隔开。约束:


  1. 作为主键的成员不能为复合数据类型,只能是基本内置数据类型。

  2. 作为主键的成员其取值不能为 NULL。


<struct name="GameItem" primarykey="gameid,itemid">  <entry name="gameid" type="uint" />  <entry name="itemid" type="uint" />  <entry name="buytime" type="datetime" />  <entry name="validtime" type="datetime" /></struct>
复制代码


根据上面的描述,GameItem 的数据表使用 gameid 和 itemid 两个成员作为主键。

分表属性(分表因子) splittablekey

splittablekey 属性指明计算当前结构与具体数据表映射关系的数据源,其取值为以当前元素为父元素的特定子元数据成员。约束:作为此成员不能为复合数据类型,只能是基本内置数据类型(void 类型除外)。


<struct name="GameItem" primarykey="gameid,itemid" splittablekey="gameid">  <entry name="gameid" type="uint" />  <entry name="itemid" type="uint" />  <entry name="buytime" type="datetime" />  <entry name="validtime" type="datetime" /></struct>
复制代码

本地索引 index

基于 TcaplusDB 主键字段建立的索引,在建表时随表一起建立,并且一旦表创建后,就不能再增加、修改和删除本地索引了,删除表的时候,本地索引会一并删除。


  • 本地索引是实时索引,当插入或者删除数据时,会同时更新索引数据。

  • 本地索引的字段必须包含在主键字段中,并且字段中还必须包含分表因子,因此,查询时最终只会落到一个数据分片上进行查询。

  • 本地索引只支持等值查询。

  • 一个表可以建立多个本地索引,查询时必须包含某一个本地索引的全部字段。

  • 目前只有 generic 表支持本地索引。


<struct name="PLAYERONLINECNT" version="1" primarykey="TimeStamp,GameSvrID,GameAppID" splittablekey="TimeStamp">    <entry name="TimeStamp"           type="uint32"     desc="单位为分钟" />    <entry name="GameSvrID"         type="string"     size="64" />    <entry name="GameAppID"         type="string"     size="64" desc="gameapp id" />    <index name="index_1"  column="TimeStamp"/>    <index name="index_2"  column="TimeStamp, GameSvrID"/>    <index name="index_3"  column="TimeStamp, GameAppID"/></struct>
复制代码


如上文所示,index 的 name 不可以重复,且必须按照 index_i 的规则依次递增,且不同的 index 必须拥有不同的 column。

通用属性

这里的通用属性是指除了根元素外,所有的非根元素都可以具有的属性。对于那些不通用的属性,在描述相关的元素的时候统一进行描述。但是对于 include 元素,通用属性中只有 name 属性才有意义。

id

id 属性表明了该元素的唯一标识,在 DR 提供的 API 中可以利用此 id 来查找、定位特定的元素。id 的取值可以是一个字面量的数字,也可以是一个 Macro 的名字(对于非 Macro 类型的元素)。约束:


  1. 同一父元素下的所有子元素的 id 属性值不能重复。

  2. metalib 元素的 id 属性只能是一个字面量的数字,不可以是 Macro 名字。

  3. struc/union 元素的 id 属性值只能是 0 或者正整数。

name

name 属性提供该元素的字符类型标识。在 DR 提供的 API 中可以利用此 Name 来查找、定位特定的元素。约束:


  1. 同一父元素下的所有子元素的 Name 属性的值除后面描述的特例外是不可重复的。

  2. name 属性的属性值区分大小写,即 name="net"与 name="NET"认为是不同的属性值。

  3. 元数据描述的所有元素必须包含 name 属性。

cname

cname 属性提供该元素的中文标识名。通过提供有意义的中文名,可以对元素的意义有更好的理解。(目前已知的应用领域是从 Excel 表中读取数据生成所需的内存结构)。

version

版本属性指明了该元素被引入时该元数据描述库的版本号。该版本号在打包、解包的时候提供裁减的依据。version 的取值可以是一个字面量的数字,也可以是一个 Macro 的名字(对于非 Macro 类型的元素)。约束:


  1. metalib,struct,union 元素必须包含 version 属性。

  2. 对于 struct 和 union 元素,其 version 属性指明其基准版本号,即该版本号表明该元素加入到 metalib 时的库版本号。Metalib,struct,union,entry 元素的 version 属性的约束:

  3. metalib 元素必须指定 version 属性,此属性指明该元数据描述库的当前版本,称为库版本。库版本号的变化反映了整个元数据描述库的变化情况,只要库发生了变化,库版本号就必须同步保持变化。库版本号永远只能增加,不能减少。

  4. 每个 struc 和 union 元数据都必须包含 version 属性,此属性表明该 Meta 创建时的库版本号,称为元数据基准版本号(MetaBaseVersion)。

  5. 每个元数据成员有自己的当前版本号,该版本号表明该 MetaMember 被添加时的库版本号,即该版本号表明了该元数据成员是在那个库版本中被引入的。当一个 MetaMember 没有定义其版本号时,缺省继承它所在的元数据的基准版本号。

  6. 一个元数据(Meta)的当前版本号,此版本号为其成员中当前版本号的最大值。

desc

描述信息。对该元素的一些简要描述,表明该元素的用途、意义等等。

metalib 元素

Metalib 元素只能包含如下子元素:include, macro, macrosgroup, struct, union。Metalib 元素除可以包含以上描述的 id,name,version 属性外,还可以包含以下属性:tagsetversion。

name

只有 name 属性值相同的 XML 描述文件才能放在一起生成元数据描述库,除非其 name 属性为空串。Metalib 的 name 属性类似于名字空间。

tagsetversion

此属性指明元数据描述使用的 XML 标签集的版本信息,通过此属性处理程序可以兼容使用不同版本元数据标签集定义的 XML 描述文件。此属性的值为无符号整数,并且必须是递增的,每调整一次元数据描述 XML 标签集定义,必须使用新的版本号。如果 XML 文件中,metaLib 元素中没有包含此属性,则处理程序缺省按 DR API 支持的最新版本的标签定义进行解析。约束:本文档中元数据描述 XML 标签集 tagsetversion 值定义为 1,即使用本文档中定义的标签生成的 XML 描述文件,其 metaLib 元素的 tagsetversion 属性值为 1。

include 元素

include 元素必须是 metalib 元素的子元素。include 元素用于指示 XML 文件间的依赖关系。Include 元素只需要定义 file 属性,但是建议定义 name(通用)属性。定义全局唯一的 name 属性,有助于在 tdr 进行 include 元素规范性检测时,对不规范的地方提供详细的定位信息。在严格意义上,include 不属于元数据库,include 元素不影响元数据库的 hash 值,不受版本的约束,tdr 不对 include 节点的 name 属性做唯一性检查。当使用 tdr 的 xml2h 功能时,include 元素被转换为头文件中的 #include 宏定义,file 属性值对应的文件路径名中的 xml 后缀被直接替换为 h。例如,XML 文件中的 include 元素


<include name="head" file="./head.xml">
复制代码


对应头文件中的如下宏定义:


#include "./head.h"
复制代码


当使用 tdr 的 cplusplus 功能时,include 元素被转换为头文件中的 #include 宏定义,file 属性值对应的文件路径名中的 xml 后缀被直接替换为 h,并删除了路径中的目录信息。之所以删除路径中的目录信息,是因为对于 cplusplus 功能,tdr 把所有的文件都生成在相同的目录中。例如,XML 文件中的 include 元素


<include name="head" file="../comm.xml">
复制代码


对应头文件中的如下宏定义:


#include "comm.h"
复制代码


对于 XML 文件中出现的多个 include 元素,tdr 依次处理这些 include 元素。

file

file 属性用于指明当前 XML 文件依赖的其他 XML 文件。如果 XML 文件中 include 元素的 file 属性值是当前 XML 文件路径本身或为””,则此 include 元素不起作用。约束:file 属性的值(XML 文件路径)指定的文件必须出现在(启动 tdr 工具时的)命令行指定的 XML 文件列表中。

macro 元素

macro 元素可以是 metalib 元素的子元素,也可以是 macrosgoup 元素的子元素。macro 元素与 C 语言中的宏的意义类似,在实际的处理中也是映射到 C 语言的宏。Macro 元素相对简单,只需要有 name(通用)属性和 value 属性就可以了。

value

value 属性用于指明该 macro 代表的值是多少(相比与 C 语言中宏的概念,name 属性的值是宏的名字,value 属性的值是宏的内容)。其取值可以是一个字面量的数字,也可以是一个之前已定义的 Macro 的名字。约束:目前 value 属性值是通过 int 数据类型来存储的,因此只能处理 int 数据类型值域范围里的数据。

macrosgroup 元素

macrosgroup 元素用于对 macro 元素进行分类,每一类 macro 元素组成一个宏定义组。Macrosgroup 只需包含 name 和 desc 属性就可以了。macrosgroup 元素的子元素为 macro 元素,当然 macro 元素也可以不属于任何宏定义组。约束:


  1. macrosgroup 元素必须指定 name 属性。

  2. macrosgroup 的 macro 子元素的 value 属性值必须唯一,即 value 属性值相同的 macro 元素不能放入同一个 macrosgroup 元素下。


<macro name="MAX_BODY_LEN" value="32000" /><macrosgroup name=”MsgID” desc=”id of net message” >  <macro name="CMD_LOGIN" value="0" />  <macro name="CMD_LOGOUT" value="1" /></macrosgroup >
复制代码

struct 元素

struct 元素必须是 metalib 元素的子元素,在 tcaplus 中一张表对应一个 struct。struct 元素是 DR 中最复杂的元素,与 C 语言的 struct 概念类似。

size

size 属性指明该 struct 的内存占用大小。如果不指明 size 属性,那么该 struct 的大小会通过计算成员的大小后自动得出该 struct 的大小。但是通过指定 size 属性,可以让该 struct 预占多一些空间,size 属性指定的大小不能比自动计算出来的大小更小。

align

align 属性对应于编译器的 #pragma pack 指令。利用 align 属性可以指定该 struct 内部所有成员的对齐大小。如果不指定 align 属性,缺省对齐大小为 1。指定 align 属性会影响到该结构体的大小、每个成员的偏移。

customattr2

customattr2 属性用于定义表格的属性,包括:


  1. TableType:用于指定表格类型,如 list 或者 sortlist,若不指定类型默认为 generic 表,且 generic 表无需添加 customattr2 属性,关于表格类型的说明请见 Generic表和List表

  2. ListNum:用于定义 list 或者 sortlist 表中,单个 key 最多可以指向多少个 value 值,若超过该值可指定从头部或尾部删除老元素。

  3. SortFieldNum:用于 sortlist 表中,表示该表有多少个排序字段,每个排序字段需要用 customattr2 标识,如第一个为“sort1”,第二个“sort2”。

  4. SortRule:用于 sortlist 表中,表示该表的排序方式,如 DESC 表示降序,INSC 升序。如果有多个排序字段,按照 sort 的序号进行排序,序号小的字段优先级更高。比如排序是降序:sort1 不同时按 sort1 降序;sort1 相同时按 sort2 降序,以此类推。


<struct name="table_Sortlist_single" primarykey="key, name" customattr2="TableType=SORTLIST;ListNum=1023;SortFieldNum=1;SortRule=DESC" version="5" desc="用于list表遍历测试, 需要4个shard, 建表list最大1023个元素" >    ...</struct>
复制代码

entry 子元素

entry 对应的是元数据成员的概念,下面描述了 entry 元素可以包含的属性。

type 属性

指明 entry 数据成员的数据类型;其取值为可以为基本内置数据类型,也可以为自定义的复合数据类型,在 DR API 中对 type 属性值不区分大小写。约束:自定义复合类型不支持后向引用。


<struct name="type1"></struct><struct name="type2">  <entry name="item1" type="int" />  <entry name="item2" type="float" />  <entry name="item3" type="type1" /></struct>
复制代码

size 属性

size 属性指明该元素的内存占用大小。如果不指明 size 属性,那么该元素的大小会通过计算成员的大小后自动得出该元素的大小。但是通过指定 size 属性,可以让该元素预占多一些空间,size 属性指定的大小不能比自动计算出来的大小更小。其取值为正整数或合法的宏定义。约束:


  1. 对于自定义类型(union/struct)元素,entry 本身设置的 size 属性将忽略,将以 union/struct 元素中定义的 size 属性为准。

  2. 对于内置数据类型,目前只有 string,wstring 类型支持 size 属性,其他内置数据类型不支持 size 属性。


<struct name="type1" >  <entry name="name" type="string" size="32" />  <entry name="pass" type="string" size="32" />  </struct>
复制代码

count 属性

count 属性指明了当前元数据成员的个数(数组大小)。count 可以是字面量的数字,也可以是一个 Macro。count 属性如果不指定,缺省值为"1",取值范围为:>=1 的整数,如果为 0,表明该元数据成员的个数不确定,此时必须使用 refer 属性来指明可以用于确定数组大小的元数据成员。约束:


  1. count 属性值为 0 的元素只能是一个元数据结构的最后一个成员。并且如果一个元数据里面包含有这样的元数据成员,该元数据就只能作为最后一个成员被包含在其他的元数据结构里。


<macro name="MAX_COUNT" value="100" />
<struct name="type1"> <entry name="item1" type="int" count="10" /> <entry name="item2" type="float" count="MAX_COUNT" /> <entry name="is_exist" type="int" /> <entry name="item3" type="int" refer="is_exist" /> <entry name="total" type="int" /> <entry name="item4" type="int" count="0" refer="total" /></struct>
复制代码

refer 属性

refer 属性通常指向该元数据结构中的另一个元数据成员。当前元数据成员是数组时,refer 属性指向的元素的值指明了该数据成员的实际大小。当前元数据成员是单一元素时,refer 属性指向的元素的值指明了该数据成员是否在实际数据中存在(用于处理 Option 的数据)。取值为:该元素的直接父元素包含的特定子元素(不支持后向引用,值元素必须在当前元素之前)。


<struct name="type1">  <entry name="item1" type="int" />  <entry name="item2" type="float" count="10" refer="item1" /></struct>
复制代码


扩展情况:有时候还需要引用跟当前元素不在同一层次的子元素,此时使用类似 Path.Target 的形式来指定。


<struct name="type1">  <entry name="item1" type="int" />  <entry name="item2" type="int" /></struct>
<struct name="type2"> <entry name="head" type="type1" /> <entry name="item4" type="float" count="10" refer="head.item1" /></struct>
复制代码


约束:


  1. refer 属性所指元素的值必须小于等于此元素的 count 属性的值,以上例为例 head.item1 的值必须不大于 10;当元素是单一元素时,count 属性取默认值 1,这时 refer 属性所指元素的值只能为 1 或 0,取值为 1 时表示比元素存在,取值为 0 时表示此元素不存在。

  2. 此元素的 refer 属性所指元素,不能同时被其它元素或父元素指定为 sizeinfo 或 versionindicator 属性。

defaultvalue 属性

defaultvalue 属性指明了如何对该元数据成员的值在没有显式定义时该怎么取值。取值:合法的字符串,同时该串的内容应该跟该元数据成员的类型匹配。如果不指定 defaultvalue 属性,则缺省值为 0(同时对于数组不作填充处理)。约束:


  1. 目前支持对内置数据类型设定缺省值,对于自定义复杂数据类型不支持设置缺省值。


<struct name="type1">  <entry name="item1" type="int" count="100" defaultvalue="100" />  <entry name="item2" type="date" defaultvalue="2009-11-03" />  <entry name="item3" type="int"/></struct>
复制代码

select 属性

select 属性和 refer 属性类似,通常指向该元数据结构中的另一个元数据成员。select 属性指明了如何选择 union 中数据成员的方法。通常是使用 select 属性指向的元素的值来决定 union 中到底使用哪个数据成员。取值为:该元素的直接父元素包含的特定子元素(不支持后向引用,值元素必须在当前元素之前)。


<union name="type1">  <entry name="item1" type="int" id="1" />  <entry name="item2" type="int" id="2" /></union>
<struct name="type2"> <entry name="selector" type="short" /> <entry name="item3" type="type1" select="selector" /></struct>
复制代码

customattr2 属性

customattr2 属性用于表示字段是否属于排序字段,比如排序是降序:sort1 不同时按 sort1 降序;sort1 相同时按 sort2 降序,以此类推。


<struct name="table_Sortlist_single" primarykey="key, name" customattr2="TableType=SORTLIST;ListNum=1023;SortFieldNum=1;SortRule=DESC" version="5" desc="用于list表遍历测试, 需要4个shard, 建表list最大1023个元素" >    <entry name="key"      type="uint32"   desc="单个uint32作为KEY的时候, hashcode = key % 10000"/>    <entry name="name"     type="int16" />    <entry name="type_int16" type="int16" desc="type_int16" customattr2="sort1"/>    <entry name="type_int64" type="int64" desc="type_int64" customattr2="sort2"/></struct>
复制代码

Union 元素

union 元素必须是 metalib 元素的子元素。union 元素与 C 语言中的 union 类似。在定义上,union 元素和 struct 元素基本相同。union 元素与 struct 元素的区别与 C 语言中 union 和 struct 的区别相同。

entry 子元素

和 struct 元素一样,entry 对应的也是元数据成员的概念。union 中的 entry 子元素除了可以拥有 struct 中的 entry 子元素一样的属性外,还可以拥有另外两个额外的属性。约束:


  1. union 中不能再包含有 union 类型的元数据成员。

minid 和 maxid 属性

通常使用 ID 属性来作为确定 union 中到底选择那个元数据成员的依据。但是在实际应用中,可能需要使用一个范围来对应一个元数据成员,这时候使用 minid 和 maxid 属性来表示。当使用 minid 和 maxid 时,表示的意义是区间:[minid, maxid]。当使用 ID 时,表示的意义是区间:[ID, ID]。union 类型的数据结构的子元素可以没有 ID,此时表示该子元素是缺省的元素。当其他子元素都无法匹配的时候,该子元素匹配选择。为了支持多重取值范围的情况,对于 union 类型的元数据结构的子元素的名字可以重复,但是这些同名的子元素的类型必需完全一致(对于这种情况,在编译的时候需要给出一些 Info 类型的提示)。约束:


  1. union 元素的子元素,有且仅有一个可以没有 ID 属性。

  2. maxid,minid 属性必须同时出现。

  3. 如果同时出现了 maxid,minid,id 属性,则在 union 结构中选择成员时,以 maxid 和 minid 两个属性为准。


<union name="type1">  <entry name="example" type="int" minid="1" maxid="100" />  <entry name="example" type="int" id="108" />  <entry name="example" type="int" minid="200" maxid="300" />  <entry name="example" type="int" id="-99" />  <entry name="item2" type="int" id="2" /></union>
复制代码


则 example 子元素对应的选择器的取值范围可以是:{[1,100],[108,108],[200,300],[-99,-99]}。





TcaplusDB 是腾讯出品的分布式 NoSQL 数据库,存储和调度的代码完全自研。具备缓存+落地融合架构、PB 级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。

用户头像

数据人er

关注

还未添加个人签名 2021.03.09 加入

还未添加个人简介

评论

发布
暂无评论
【深入理解TcaplusDB技术】详细介绍TDR 表中Tcaplus的相关属性_数据库_数据人er_InfoQ写作社区