1syntax = "proto2";
2
3package otsprotocol;
4
5message Error {
6    required string code = 1;
7    optional string message = 2;
8}
9
10enum PrimaryKeyType {
11    INTEGER = 1;
12    STRING = 2;
13    BINARY = 3;
14}
15
16enum PrimaryKeyOption {
17    AUTO_INCREMENT = 1;
18}
19
20message PrimaryKeySchema {
21    required string name = 1;
22    required PrimaryKeyType type = 2;
23    optional PrimaryKeyOption option = 3;
24}
25
26message PartitionRange {
27    required bytes begin = 1; // encoded as SQLVariant
28    required bytes end = 2; // encoded as SQLVariant
29}
30
31enum BloomFilterType {
32    NONE = 1;
33    CELL = 2;
34    ROW = 3;
35}
36
37message TableOptions {
38    optional int32 time_to_live = 1; // 可以动态更改
39    optional int32 max_versions = 2; // 可以动态更改
40    optional BloomFilterType bloom_filter_type = 3; // 可以动态更改
41    optional int32 block_size = 4; // 可以动态更改
42    optional int64 deviation_cell_version_in_sec = 5; // 可以动态修改
43}
44
45message TableMeta {
46    required string table_name = 1;
47    repeated PrimaryKeySchema primary_key = 2;
48    repeated DefinedColumnSchema defined_column = 3;
49    repeated IndexMeta index_meta = 4;
50}
51
52/**
53 * 表的状态变更只与用户的操作对应，内部的机器failover等状况不对应表的状态变更。
54 * 有三个考虑：
55 *     一是一般场景下用户只会在做了对表的修改操作后才会去检查表的状态；
56 *     二是内部机器failover导致访问异常到用户能够查看到表的状态变更这两个时刻之间会有一段延迟，无法将表的不可服务状态与用户查看到的表的状态完全匹配上。
57 *     三是内部机器failover后不能说是表的整个状态变更，而应该是partition的状态变更，对应表的状态就是PARTIAL_FAILOVER，这个partial的粒度无法体现，会让用户更加困惑。
58 */
59enum TableStatus {
60    ACTIVE = 1; // 表处于可服务状态。
61    INACTIVE = 2; // 用户通过UnloadTable将表禁用。
62    LOADING = 3; // 表正在被创建，partition还未全部加载完毕；或者表刚从INACTIVE状态被Enable。
63    UNLOADING = 4; // 表正在被删除（从delete table到partition完全unload的这段期间）或者表从ACTIVE状态被Unload。
64    UPDATING = 5; // 表正在被更新（table属性变更、预留吞吐量变更）。
65}
66
67enum RowExistenceExpectation {
68    IGNORE = 0;
69    EXPECT_EXIST = 1;
70    EXPECT_NOT_EXIST = 2;
71}
72
73message Condition {
74    required RowExistenceExpectation row_existence = 1;
75    optional bytes column_condition      = 2;
76}
77
78message CapacityUnit {
79    optional int32 read = 1;
80    optional int32 write = 2;
81}
82
83message ReservedThroughputDetails {
84    required CapacityUnit capacity_unit = 1; // 表当前的预留吞吐量的值。
85    required int64 last_increase_time = 2; // 最后一次上调预留吞吐量的时间。
86    optional int64 last_decrease_time = 3; // 最后一次下调预留吞吐量的时间。
87}
88
89message ReservedThroughput {
90    required CapacityUnit capacity_unit = 1;
91}
92
93message ConsumedCapacity {
94    required CapacityUnit capacity_unit = 1;
95}
96
97message StreamSpecification {
98    required bool enable_stream = 1;
99    optional int32 expiration_time = 2;
100}
101
102message StreamDetails {
103    required bool enable_stream = 1;
104    optional string stream_id = 2;
105    optional int32 expiration_time = 3;
106    optional int64 last_enable_time = 4;
107}
108
109/* #############################################  CreateTable  ############################################# */
110/**
111 * table_meta用于存储表中不可更改的schema属性，可以更改的ReservedThroughput和TableOptions独立出来，作为UpdateTable的参数。
112 * 加入GlobalIndex和LocalIndex之后，结构会变为：
113 * message CreateTableRequest {
114 *         required TableMeta table_meta = 1;
115 *         required ReservedThroughput reserved_throughput = 2;
116 *         required TableOptions table_options = 3;
117 *         repeated LocalIndex local_indexes = 4; // LocalIndex不再单独包含ReservedThroughput和TableOptions，其与主表共享配置。
118 *         repeated GlobalIndex global_indexes = 5; // GlobalIndex内单独包含ReservedThroughput和TableOptions
119 * }
120 */
121message CreateTableRequest {
122    required TableMeta table_meta = 1;
123    required ReservedThroughput reserved_throughput = 2; // 未放在TableOptions内，原因是UpdateTableResponse中会返回ReservedThroughputDetails，而TableOptions没有类似的返回结构。
124    optional TableOptions table_options = 3;
125    repeated PartitionRange partitions = 4;
126    optional StreamSpecification stream_spec = 5;
127    repeated IndexMeta index_metas = 7;
128}
129
130message CreateTableResponse {
131}
132
133/* ######################################################################################################### */
134
135
136/* #############################################  UpdateTable  ############################################# */
137message UpdateTableRequest {
138    required string table_name = 1;
139    optional ReservedThroughput reserved_throughput = 2;
140    optional TableOptions table_options = 3;
141    optional StreamSpecification stream_spec = 4;
142}
143
144message UpdateTableResponse {
145    required ReservedThroughputDetails reserved_throughput_details = 1;
146    required TableOptions table_options = 2;
147    optional StreamDetails stream_details = 3;
148}
149/* ######################################################################################################### */
150
151/* #############################################  DescribeTable  ############################################# */
152message DescribeTableRequest {
153    required string table_name = 1;
154}
155
156message DescribeTableResponse {
157    required TableMeta table_meta = 1;
158    required ReservedThroughputDetails reserved_throughput_details = 2;
159    required TableOptions table_options = 3;
160    required TableStatus table_status = 4;
161    optional StreamDetails stream_details = 5;
162    repeated bytes shard_splits = 6;
163    repeated IndexMeta index_metas = 8;
164}
165/* ########################################################################################################### */
166
167/* #############################################  ListTable  ############################################# */
168message ListTableRequest {
169}
170
171/**
172 * 当前只返回一个简单的名称列表，需要讨论是否有业务场景需要获取除了表名之外的其他信息。
173 * 其他信息可以包含预留吞吐量以及表的状态，这个信息只能是一个粗略的信息，表的详细信息还是需要通过DescribeTable来获取。
174 */
175message ListTableResponse {
176    repeated string table_names = 1;
177}
178/* ####################################################################################################### */
179
180/* #############################################  DeleteTable  ############################################# */
181message DeleteTableRequest {
182    required string table_name = 1;
183}
184
185message DeleteTableResponse {
186}
187/* ######################################################################################################### */
188
189/* #############################################  LoadTable  ############################################# */
190message LoadTableRequest {
191    required string table_name = 1;
192}
193
194message LoadTableResponse {
195}
196/* ######################################################################################################### */
197
198/* #############################################  UnloadTable  ############################################# */
199message UnloadTableRequest {
200    required string table_name = 1;
201}
202
203message UnloadTableResponse {
204
205}
206/* ########################################################################################################## */
207
208/**
209 * 时间戳的取值最小值为0，最大值为INT64.MAX
210 * 1. 若要查询一个范围，则指定start_time和end_time
211 * 2. 若要查询一个特定时间戳，则指定specific_time
212 */
213message TimeRange {
214    optional int64 start_time = 1;
215    optional int64 end_time = 2;
216    optional int64 specific_time = 3;
217}
218
219/* #############################################  GetRow  ############################################# */
220
221enum ReturnType {
222    RT_NONE = 0;
223    RT_PK = 1;
224    RT_AFTER_MODIFY = 2;
225}
226
227message ReturnContent {
228    optional ReturnType return_type = 1;
229    repeated string return_column_names = 2;
230}
231
232/**
233 * 1. 支持用户指定版本时间戳范围或者特定的版本时间来读取指定版本的列
234 * 2. 目前暂不支持行内的断点
235 */
236message GetRowRequest {
237    required string table_name = 1;
238    required bytes primary_key = 2; // encoded as InplaceRowChangeSet, but only has primary key
239    repeated string columns_to_get = 3; // 不指定则读出所有的列
240    optional TimeRange time_range = 4;
241    optional int32 max_versions = 5;
242    optional bool cache_blocks = 6 [default = true]; // 本次读出的数据是否进入BlockCache
243    optional bytes filter = 7;
244    optional string start_column = 8;
245    optional string end_column = 9;
246    optional bytes token = 10;
247    optional string transaction_id = 11;
248}
249
250message GetRowResponse {
251    required ConsumedCapacity consumed = 1;
252    required bytes row = 2; // encoded as InplaceRowChangeSet
253    optional bytes next_token = 3;
254}
255/* #################################################################################################### */
256
257/* #############################################  UpdateRow  ############################################# */
258message UpdateRowRequest {
259    required string table_name = 1;
260    required bytes row_change = 2;
261    required Condition condition = 3;
262    optional ReturnContent return_content = 4;
263    optional string transaction_id = 5;
264}
265
266message UpdateRowResponse {
267    required ConsumedCapacity consumed = 1;
268    optional bytes row = 2;
269}
270
271/* ####################################################################################################### */
272
273/* #############################################  PutRow  ############################################# */
274
275
276/**
277 * 这里允许用户为每列单独设置timestamp，而不是强制整行统一一个timestamp。
278 * 原因是列都是用统一的结构，该结构本身是带timestamp的，其次强制统一timestamp增强了规范性但是丧失了灵活性，且该规范性没有明显的好处，反而带来了结构的复杂。
279 */
280message PutRowRequest {
281    required string table_name = 1;
282    required bytes row = 2; // encoded as InplaceRowChangeSet
283    required Condition condition = 3;
284    optional ReturnContent return_content = 4;
285    optional string transaction_id = 5;
286}
287
288message PutRowResponse {
289    required ConsumedCapacity consumed = 1;
290    optional bytes row = 2;
291}
292/* #################################################################################################### */
293
294/* #############################################  DeleteRow  ############################################# */
295/**
296 * OTS只支持删除该行的所有列所有版本，不支持：
297 *  1. 删除所有列的所有小于等于某个版本的所有版本
298 */
299message DeleteRowRequest {
300    required string table_name = 1;
301    required bytes primary_key = 2; // encoded as InplaceRowChangeSet, but only has primary key
302    required Condition condition = 3;
303    optional ReturnContent return_content = 4;
304    optional string transaction_id = 5;
305}
306
307message DeleteRowResponse {
308    required ConsumedCapacity consumed = 1;
309    optional bytes row = 2;
310}
311/* ####################################################################################################### */
312
313/* #############################################  BatchGetRow  ############################################# */
314/**
315 * HBase支持Batch操作的每行都拥有不同的查询参数，OTS不支持。
316 */
317message TableInBatchGetRowRequest {
318    required string table_name = 1;
319    repeated bytes primary_key = 2; // encoded as InplaceRowChangeSet, but only has primary key
320    repeated bytes token = 3;
321    repeated string columns_to_get = 4;  // 不指定则读出所有的列
322    optional TimeRange time_range = 5;
323    optional int32 max_versions = 6;
324    optional bool cache_blocks = 7 [default = true]; // 本次读出的数据是否进入BlockCache
325    optional bytes filter = 8;
326    optional string start_column = 9;
327    optional string end_column = 10;
328}
329
330message BatchGetRowRequest {
331    repeated TableInBatchGetRowRequest tables = 1;
332}
333
334message RowInBatchGetRowResponse {
335    required bool is_ok = 1;
336    optional Error error = 2;
337    optional ConsumedCapacity consumed = 3;
338    optional bytes row = 4; // encoded as InplaceRowChangeSet
339    optional bytes next_token = 5;
340}
341
342message TableInBatchGetRowResponse {
343    required string table_name = 1;
344    repeated RowInBatchGetRowResponse rows = 2;
345}
346
347message BatchGetRowResponse {
348    repeated TableInBatchGetRowResponse tables = 1;
349}
350/* ######################################################################################################### */
351
352/* #############################################  BatchWriteRow  ############################################# */
353
354enum OperationType {
355    PUT = 1;
356    UPDATE = 2;
357    DELETE = 3;
358}
359
360message RowInBatchWriteRowRequest {
361    required OperationType type = 1;
362    required bytes row_change = 2; // encoded as InplaceRowChangeSet
363    required Condition condition = 3;
364    optional ReturnContent return_content = 4;
365}
366
367message TableInBatchWriteRowRequest {
368    required string table_name = 1;
369    repeated RowInBatchWriteRowRequest rows = 2;
370}
371
372message BatchWriteRowRequest {
373    repeated TableInBatchWriteRowRequest tables = 1;
374    optional string transaction_id = 2;
375}
376
377message RowInBatchWriteRowResponse {
378    required bool is_ok = 1;
379    optional Error error = 2;
380    optional ConsumedCapacity consumed = 3;
381    optional bytes row = 4;
382}
383
384message TableInBatchWriteRowResponse {
385    required string table_name = 1;
386    repeated RowInBatchWriteRowResponse rows = 2;
387}
388
389message BatchWriteRowResponse {
390    repeated TableInBatchWriteRowResponse tables = 1;
391}
392/* ########################################################################################################### */
393
394/* #############################################  GetRange  ############################################# */
395enum Direction {
396    FORWARD = 0;
397    BACKWARD = 1;
398}
399
400/**
401 * HBase支持以下参数：
402 *     1. TimeRange或指定time
403 *     2. Filter（根据列值或列名来过滤）
404 * 我们只支持给同版本的选择条件。
405 */
406message GetRangeRequest {
407    required string table_name = 1;
408    required Direction direction = 2;
409    repeated string columns_to_get = 3;  // 不指定则读出所有的列
410    optional TimeRange time_range = 4;
411    optional int32 max_versions = 5;
412    optional int32 limit = 6;
413    required bytes inclusive_start_primary_key = 7; // encoded as InplaceRowChangeSet, but only has primary key
414    required bytes exclusive_end_primary_key = 8; // encoded as InplaceRowChangeSet, but only has primary key
415    optional bool cache_blocks = 9 [default = true]; // 本次读出的数据是否进入BlockCache
416    optional bytes filter = 10;
417    optional string start_column = 11;
418    optional string end_column = 12;
419    optional bytes token = 13;
420    optional string transaction_id = 14;
421}
422
423message GetRangeResponse {
424    required ConsumedCapacity consumed = 1;
425    required bytes rows = 2; // encoded as InplaceRowChangeSet
426    optional bytes next_start_primary_key = 3; // 若为空，则代表数据全部读取完毕. encoded as InplaceRowChangeSet, but only has primary key
427    optional bytes next_token = 4;
428}
429/* ###################################################################################################### */
430/* #############################################  Stream  ############################################# */
431
432message ListStreamRequest {
433    optional string table_name = 1;
434}
435
436message Stream {
437    required string stream_id = 1;
438    required string table_name = 2;
439    required int64 creation_time = 3;
440}
441
442message ListStreamResponse {
443    repeated Stream streams = 1;
444}
445
446message StreamShard {
447    required string shard_id = 1;
448    optional string parent_id = 2;
449    optional string parent_sibling_id = 3;
450}
451
452enum StreamStatus {
453    STREAM_ENABLING = 1;
454    STREAM_ACTIVE = 2;
455}
456
457message DescribeStreamRequest {
458    required string stream_id = 1;
459    optional string inclusive_start_shard_id = 2;
460    optional int32 shard_limit = 3;
461}
462
463message DescribeStreamResponse {
464    required string stream_id = 1;
465    required int32 expiration_time = 2;
466    required string table_name = 3;
467    required int64 creation_time = 4;
468    required StreamStatus stream_status = 5;
469    repeated StreamShard shards = 6;
470    optional string next_shard_id = 7;
471}
472
473message GetShardIteratorRequest {
474    required string stream_id = 1;
475    required string shard_id = 2;
476    optional int64 timestamp = 3;
477    optional string token = 4;
478}
479
480message GetShardIteratorResponse {
481    required string shard_iterator = 1;
482    optional string next_token = 2;
483}
484
485message GetStreamRecordRequest {
486    required string shard_iterator = 1;
487    optional int32 limit = 2;
488}
489
490enum ActionType {
491    PUT_ROW = 1;
492    UPDATE_ROW = 2;
493    DELETE_ROW = 3;
494}
495
496message GetStreamRecordResponse {
497    message StreamRecord {
498        required ActionType action_type = 1;
499        required bytes record = 2;
500    }
501    repeated StreamRecord stream_records = 1;
502    optional string next_shard_iterator = 2;
503}
504
505/* +++++ ComputeSplitPointsBySize  +++++ */
506message ComputeSplitPointsBySizeRequest {
507    required string table_name = 1;
508    required int64 split_size = 2; // in 100MB
509}
510
511message ComputeSplitPointsBySizeResponse {
512    required ConsumedCapacity consumed = 1;
513    repeated PrimaryKeySchema schema = 2;
514
515    /**
516     * Split points between splits, in the increasing order
517     *
518     * A split is a consecutive range of primary keys,
519     * whose data size is about split_size specified in the request.
520     * The size could be hard to be precise.
521     *
522     * A split point is an array of primary-key column w.r.t. table schema,
523     * which is never longer than that of table schema.
524     * Tailing -inf will be omitted to reduce transmission payloads.
525     */
526    repeated bytes split_points = 3;
527
528    /**
529     * Locations where splits lies in.
530     *
531     * By the managed nature of TableStore, these locations are no more than hints.
532     * If a location is not suitable to be seen, an empty string will be placed.
533     */
534     message SplitLocation {
535         required string location = 1;
536         required sint64 repeat = 2;
537     }
538     repeated SplitLocation locations = 4;
539}
540/* -------------------------------------- */
541
542enum DefinedColumnType {
543    DCT_INTEGER = 1;
544    DCT_DOUBLE = 2;
545    DCT_BOOLEAN = 3;
546    DCT_STRING = 4;
547    // field 5 is reserved for date type, not supported yet
548    // field 6 is reserved for decimal type, not supported yet
549    DCT_BLOB = 7;
550}
551
552message DefinedColumnSchema {
553    required string name = 1;
554    required DefinedColumnType type = 2;
555}
556
557enum IndexUpdateMode {
558    IUM_ASYNC_INDEX = 0;
559    IUM_SYNC_INDEX = 1;
560}
561
562enum IndexType {
563    IT_GLOBAL_INDEX = 0;
564    IT_LOCAL_INDEX = 1;
565}
566
567message IndexMeta {
568    required string name = 1;
569    repeated string primary_key = 2;
570    repeated string defined_column = 3;
571    required IndexUpdateMode index_update_mode = 4;
572    required IndexType index_type = 5;
573}
574
575message CreateIndexRequest {
576    required string main_table_name = 1;
577    required IndexMeta index_meta = 2;
578    optional bool include_base_data = 3;
579}
580
581message CreateIndexResponse {
582}
583
584message DropIndexRequest {
585    required string main_table_name = 1;
586    required string index_name = 2;
587}
588
589message DropIndexResponse {
590}
591
592/* ###########################################  LocalTransaction  ########################################### */
593message StartLocalTransactionRequest {
594    required string table_name = 1;
595    required bytes key = 2; // encoded as SQLVariant
596}
597
598message StartLocalTransactionResponse {
599    required string transaction_id = 1;
600};
601
602message CommitTransactionRequest {
603    required string transaction_id = 1;
604}
605
606message CommitTransactionResponse {
607};
608
609message AbortTransactionRequest {
610    required string transaction_id = 1;
611}
612
613message AbortTransactionResponse {
614};
615
616/* ######################################################################################################### */