提供了编程的基础技术教程

zl程序教程

您现在的位置是：首页 >  其他

当前栏目

【TcaplusDB知识库】PB表定义示例

2023-03-14 22:58:28 时间

【TcaplusDB知识库】PB表定义示例

PB表定义示例

以下是protobuf表game_players.proto的示例，您可以将文件上传到控制台并创建该表。

syntax = "proto3";         // 指定protobuf语言版本,proto3.
 
// 导入TcaplusDB公共定义服务 
import "tcaplusservice.optionv1.proto";
 
message game_players {  // 定义TcaplusDB表，包含message类型
 
// 基于选择项tcaplusservice.tcaplus_primary_key创建主键字段
// TcaplusDB单个表最多能指定8个主键字段(3.37.0及其之后版本)
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_sharding_key) = "player_id";
 
    // 基于选择项tcaplusservice.tcaplus_index创建主键索引
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";
 
    // TcaplusDB支持的数值类型:
    // int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
    // 嵌套类型: message
 
    // 主键字段
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
     
    // 普通(非主键) 字段
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
     
    payment pay = 8;
}
 
message payment {
     
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
 
}

Tcaplus相关属性

TcaplusDB 表定义可以在 protobuf 语法基础上通过 option 进行扩展，可以实现更丰富的语义功能，可定义的内容如下表所示。 详细的定义格式为：option(tcaplusservice.选项) = "值";

选项名称

功能说明

设置示例

必填

tcaplus_primary_key

设置 TcaplusDB 表主键字段

option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";

是

tcaplus_index

设置 TcaplusDB 表索引键字段

option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";

否

tcaplus_sharding_key

用户可以自定义表分片键

option(tcaplusservice.tcaplus_sharding_key) = "uin";

否

tcaplus_field_cipher_suite

如需使用字段加密功能，请参考设置示例进行设置；如果用户需要指定自己的加密算法，请参考 API 中的例子

option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite";

否

tcaplus_cipher_md5

如需使用字段加密功能，需要设置用户侧保存加密密码字符串的 MD5

option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b";

否

主键 tcaplus_primary_key

tcaplus_primary_key属性指明此元素对应数据库表的主键，如果有多个成员组成表的主键，则成员名之间用逗号（','）隔开，单个表最多能指定8个主键字段。 约束：

  1. 作为主键的成员不能为复合数据类型，只能是基本内置数据类型。
  2. 作为主键的成员其取值不能为NULL。
option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";

根据上面的描述，GameItem的数据表使用player_id, player_name, player_email三个成员作为主键。

分表属性(分表因子) tcaplus_sharding_key

如何选择分表因子

tcaplus_sharding_key属性用户可以自定义表分片键。 约束： 作为此成员不能为复合数据类型，只能是基本内置数据类型。

option(tcaplusservice.tcaplus_sharding_key) = "player_id";

本地索引 tcaplus_index

tcaplus_index属性用于设置TcaplusDB 表索引键字段。

option(tcaplusservice.tcaplus_index) = "player_email";

文件定义信息

文件定义信息区域主要定义当前表描述文件的公共信息，主要涉及如下3种类型的内容：

选项名称

功能说明

值示例

必填

syntax

指明当前文件书写的语法规范版本。

支持 proto2、proto3

是

package

指明当前文件自定义包名，包名可以避免对 message 类型之间的名字冲突。

包名信息

是

import

引入 Tcaplus 表的一些公共信息，必须在您的表定义中被引用。

tcaplusservice.optionv1.proto

是

表定义信息

表定义信息主要通过 message 定义表的格式，在 message 中可对表的扩展信息进行定义，也可以对表的字段信息进行定义。

字段信息定义

TcaplusDB 定义字段的格式为：字段修饰符 字段类型 字段名称 = 标识号[特殊定义];

字段修饰符

proto2 支持3种类型的限定修饰符，proto3 不再支持 required 修饰，默认为 optional 类型。

  • required：表示字段为必填字段，proto2 中主键字段必须被 required 修饰。
  • optional：表示此字段为可选字段，支持设定字段的默认值。
  • repeated：表示该字段可以包含0 - N个元素，其特性和 optional 一样，但是每一次可以包含多个值，可看作是在传递一个数组的值，必须指定 [packed = true] 的特殊定义。

字段类型

TcaplusDB 支持普通字段以及嵌套型字段，详细的字段介绍可参考 数据类型（PB，TDR）。

字段名称

针对当前属性而进行对字段进行命名，支持大小写字母，数字与下划线。建议字段的命名采用驼峰式命名方式，不能以数字开头。

标识号

标识号使用范围：[1,2^29 - 1]，不可使用 [19000－19999] 标识号，因为 Protobuf 协议实现中对这些标识号进行了预留，若使用，则会报错。 每个字段在进行编码时都会占用内存，而占用内存大小取决于标识号：

  • 范围 [1,15] 标识号的字段在编码时占用1个字节。
  • 范围 [16,2047] 标识号的字段在编码时占用2个字节。

特殊定义

  • 当 repeated 修饰的字段需要指定 packed=true 选项。用法如下： repeated int64 lockid = 6 [packed = true];
  • 使用 optional 修饰的字段可以通过 default = 1 指定其默认值。用法如下： optional int32 logintime = 5 [default = 1];
  • 字段类型为 string 和 bytes 类型的字段可以指定为加密字段。用法如下： required string name = 2[(tcaplusservice.tcaplus_crypto) = true];

嵌套类型信息

TcaplusDB 支持嵌套类型，嵌套类型可以包含另一个嵌套类型作为其字段，也可以在嵌套类型内定义一个新的嵌套类型。 嵌套类型的定义与表的定义相似，均是通过 message 进行声明，但是结构体中不能包含扩展信息定义，如"主键"，"索引"等定义。 TcaplusDB 支持最多128层连续嵌套，但是不建议大量使用嵌套，嵌套层数过多会导致数据访问性能降低。

message game_players {  
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
    payment pay = 8;
}
 
message payment {
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
}

PB表修改限制

  1. 主键字段不能删除。
  2. 主键字段名和字段类型不能改变。
  3. 不能增加主键字段。
  4. 普通字段有 required 标识的不能删除。
  5. 同标识号的字段名称和字段类型不能改变。
  6. 增加的普通字段名要符合命名规则,不能修改原有字段类型、名称，更不能删除原有字段。
  7. 本地索引只能新增不能删除和修改。

示例：

  1. 增加本地索引
  2. 增加字段
syntax = "proto3";         
 
import "tcaplusservice.optionv1.proto";
 
message game_players {  
 
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)"; // 增加本地索引
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;
     
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;
     
    payment pay = 8;

    string player_email_copy = 9; // 增加value字段
}
 
message payment {
     
int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;
 
}

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

相关文章