游戏数据库 TcaplusDB 表格

一、表格概述

TcaplusDB 需要预设 Schema，同时提供两种表类型：Generic 表和 List 表。Generic 表一个 Key（1个 – 8个字段）记录对应一个 Value 记录，List 表一个 Key（1个 – 7个字段）记录对应多个 Value 记录。
List 表根据是否进行排序分为普通 List 表和 SortList 表：

·对于普通 List 表，Tcaplus 内部是无序插入的，用户取出一个 Key 下的所有 Value 时，Value 内部是无序的。

·SortList 表按照某个指定的 Value 字段进行排序插入，用户可以按照从大到小或者从小到大的顺序进行取值。在 PB 和 TDR 表中都存在 Generic 表、 List 表、SortList 表这三种 Schema 模式，用户可以根据需求选择合适的模式。

如下示例的玩家表数据，该表可用于存储有关某一游戏中所有玩家的相关信息：游戏角色名、性别、种族、等级、战斗值、装备、坐骑、物品等信息。

{player_id:11474,player_name: "测试账号2",gender:0,ethnicity:"精灵",FightingPower:10,equipment: { helmet：0, Warframe：0, gloves：0, necklace：0, pants：0, Shoes：0 },horse："0"}，{player_id:11475,player_name: "测试账号1",gender:1,ethnicity:"兽人",FightingPower:1477,equipment: { helmet：1478, Warframe：21, gloves：554, necklace：12, pants：64, Shoes：122 },horse："3"}

二、记录

多个同一对象字段值的集合，称之为记录。上述示例的玩家角色表中，一个玩家角色的所有信息，由多个属性字段值组成，其所有信息表示这个玩家角色信息在此游戏的集合。单条记录支持最大10MB。

三、字段

字段描述了指定对象的某一特征。上述示例，玩家角色的一个独立属性我们称之为一个字段，如玩家角色表中的 player_name、ethnicity。

四、主键字段

由如上示例表可看出，每条记录都有标志记录唯一性的字段，用于将表中的记录区分开来，我们称之为主键字段。上述示例的玩家角色表中，主键字段包含 player_id 以及 player_name。TcaplusDB 最大支持8个主键字段。

五、普通字段

每条记录除了标志其唯一性的字段外，还有其他的属性，这些属性所构成的字段，称之为普通字段。上述示例的玩家角色表中，普通字段则为 equipment，FightingPower 等属性。TcaplusDB 支持最多128个普通字段。

六、分片字段

TcaplusDB 是分布式数据库系统，可以为表格提供更高规格的并发请求能力。如果用户设置了分片字段，TcaplusDB 将自动根据当前表格访问情况，通过对分片字段 Hash 计算从而自动调整表格分片。如果用户不设置，那么系统将默认采用主键字段作为分片字段。

分片字段的设置与后台数据分布相关，用户需要评估作为分片字段的字段取值是否离散。取值有限的字段如性别、星期等都不建议设置为分片字段，建议使用 ID、name 类的字段作为分片字段。

七、字段类型

TcaplusDB 支持多种数据类型，支持的类型如下：

字段类型	字段介绍
int32	使用可变长度编码，此类型表示值介于 -2^31 到 +2^31 之间的有符号整数，但是负数表示效率较低。
int64	使用可变长度编码，此类型表示值介于 -2^63 到 +2^63 之间的有符号整数。
uint32	使用可变长度编码，该类型表示值为 0 到 2^32 的无符号整数。
uint64	使用可变长度编码，该类型表示值为 0 到 2^64 的无符号整数。
sint32	可变长度有符号的 int 值，与常规 int32 相比，可以更有效地表示负数。
sint64	可变长度有符号的 int 值，与常规 int64 相比，可以更有效地表示负数。
bool	布尔类型，表示真 Ture 或假 False。
fixed32	定长数字类型，始终占用四个字节。如果值通常大于 2^28，则比 uint32 更有效率。
fixed64	定长数字类型，始终占用八个字节。如果值通常大于 2^56，则比 uint64 更有效率。
sfixed32	定长数字类型，始终占用四个字节。
sfixed64	定长数字类型，始终占用八个字节。
float	浮点类型，浮点数占 4 个字节，用 32 位二进制描述。
double	双精度类型，浮点数占 8 个字节，用 64 位二进制描述。
string	字符串类型，只能为 UTF-8 编码或 7 位 ASCII 文本，并且长度不能超过 2^32。
bytes	二进制类型，可以包含任意长度不超过 2^32 的字节序列。
message	嵌套类型，可连续嵌套，支持最高嵌套128层，嵌套层数过多会影响性能。

八、表格定义格式

TcaplusDB 支持 Protocol Buffers、TDR 数据存储格式，这是一种轻便高效的结构化数据存储格式，主要用于将结构化数据序列化存储。
详细关于表的格式可通过表描述语言查看。

十、基本特点

·可以建索引，请参见索引。

·最多支持8个 Key 字段，256个 Value 字段。

·单个 Key 最大1KB，单个 Value 最大10MB，整条记录最大10MB。

十一、TDR-Generic 表示例

十二、PB-Generic 表示例

message pb_generic_index_shardingkey { option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey,svrid"; option(tcaplusservice.tcaplus_index) = "index_openid(openid)"; option(tcaplusservice.tcaplus_index) = "index_openid_tconndid(openid,tconndid)"; option(tcaplusservice.tcaplus_index) = "index_full_key(openid,tconndid,timekey,svrid)"; option(tcaplusservice.tcaplus_sharding_key) = "openid"; //4个key required uint32 openid = 1; //QQ Uin required string timekey = 2[(tcaplusservice.tcaplus_size) = 20, (tcaplusservice.tcaplus_desc) = "bingo"]; required int32 tconndid = 3; required string svrid = 4; //value required string gamesvrid = 5[(tcaplusservice.tcaplus_size) = 11]; repeated property other_property= 6 ;//其他扩展属性 optional item_bag items = 7; repeated int64 lockid = 8 [packed = true]; optional bytes val = 9; optional pay_info pay = 10; optional uint32 id_uint32 = 11; optional int32 id_int32 = 12; }

十四、基本特点

·不能建索引。

·Key 字段最多只能有7个，Value 字段最多255个，各有一个要预留给系统使用。

·List 支持方便的头尾操作, 适合邮件，留言板，战斗记录等场景。

·List 表需要指定单个 Key 记录下的最大元素个数（目前最大10000），超过最大元素个数时，可指定从头部或尾部删除老元素。

·可以一次取出单个 Key 下的所有 Value，Value 内部的排列无序。

·Tcaplus 对 List 表的存储采用分级机制，包括：

·索引记录，Fullkey + (idx1,idx2,idx3,……,idxn)

·数据记录，[FullKey+idx1,value1][FullKey+idx2,value2][……][FullKey+idxn,valuen]

十五、TDR-List表示例

十六、PB-List 表示例

syntax = "proto3";package myTcaplusTable;import "tcaplusservice.optionv1.proto";message tb_online_list { option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey"; option(tcaplusservice.tcaplus_customattr) = "TableType=LIST;ListNum=1900"; int32 openid = 1; //QQ Uin int32 tconndid = 2; string timekey = 3; string gamesvrid = 4; int32 logintime = 5 ; repeated int64 lockid = 6; pay_info pay = 7; message pay_info { uint64 total_money = 1; uint64 pay_times = 2; } map<string, pay_info> projects = 8;}

十八、基本特点

最多允许4个排序字段，且在建表的xml（tdr）中指定，具体格式如下：

注意：说明：

注意：如上 customattr="TableType=SORTLIST;ListNum=1023;SortFieldNum=1" 表示该表格类型为 SORTLIST，SortRule=INSC 表示升序排列，SortFieldNum=1 表示排序字段有1个，customattr="sort1" 表示第一个排序字段。

十九、使用限制

·排序默认按照从小到大进行排序。

·暂时不允许在表变更时从无序 List 变为 SortList，不允许从 SortList 变更为无序 List，不允许表变更变换排序字段的顺序以及增减排序字段（均采用自己写 so 走表变更 Key-Value 方式实现）。

·排序字段最大字节数8B，排序字段的类型：byte, uint16,uint32,uint64,int16,int32,int64,float,double【string(包含\\0最多8B，暂时不支持)】。

·排序是指 Value 字段参与排序，而不是 Key。

20、使用说明

·排序
当已有数据结构排好序后，再采用 ListAddAfter 进行数据插入时，采用插入排序效果最佳。

·插入

·对于 ListAddAfter，流程是：先看是否已经满了，如果满了且不允许淘汰元素，则插入失败，如果满了，允许淘汰，则删掉那个元素，并且获取一个 BiggestIndex，将新元素插在对应位置，并挪动其他元素。

·对于 SortList，当用户进行 ListAddAfter 时，需要变更下 ServiceApi 里面的接口说明，因为我们默认是按照从小到大的顺序进行排序，当用户需要淘汰最后一个元素时，即淘汰最大的元素，当用户需要淘汰队头的元素时，即淘汰最小的元素。

21、TDR-Sortlist 表示例

22、PB-SortList 表示例

message pb_sortedlist { option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey,svrid"; option(tcaplusservice.tcaplus_customattr) = "TableType=SORTLIST;ListNum=1900;SortField=id_int32"; //4个key required uint32 openid = 1; //QQ Uin required string timekey = 2[(tcaplusservice.tcaplus_size) = 20, (tcaplusservice.tcaplus_desc) = "bingo"]; required int32 tconndid = 3; required string svrid = 4; //value required string gamesvrid = 5[(tcaplusservice.tcaplus_size) = 11]; repeated property other_property= 6 ;//其他扩展属性 optional item_bag items = 7; repeated int64 lockid = 8 [packed = true]; optional bytes val = 9; optional pay_info pay = 10; optional uint32 id_uint32 = 11; optional int32 id_int32 = 12; }