【深入理解TcaplusDB技術】PB表定義

關於Protobuf

Protobuf是Google開發的一種描述性語言，針對結構化資料進行序列化，同時強調簡單性和效能。 官方文件：https://developers.google.com/protocol-buffers

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

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種類型的內容：

表定義資訊

表定義資訊主要通過 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級儲存、毫秒級時延、無損水平擴充套件和複雜資料結構等特性。同時具備豐富的生態、便捷的遷移、極低的運維成本和五個九高可用等特點。客戶覆蓋遊戲、網際網路、政務、金融、製造和物聯網等領域。