查詢接口

表格存儲Tablestore作為大資料存儲服務，提供了多種資料輸出接口，主要包含：單行讀（GetRow）、批量讀（BatchGetRow）、範圍讀（GetRange）、多元索引檢索（Search）以及通道服務的資料訂閱（Tunnel Service）。本文将詳細講述範圍讀的功能、使用與限制。

功能說明

GetRange接口提供了Tablestore資料的範圍讀取能力。通過接口，範圍内資料将會按照指定的順序（正序或逆序）逐頁傳回。使用者需要提供範圍的起始、終止的主鍵，來限定資料的範圍。若總資料未能一個請求完整傳回，可以通過連續翻頁的方式，持續周遊下一頁，知道擷取完整結果。

限制條件

一次傳回資料的行數超過 5000 行，或者傳回資料的資料大小大于 4 MB。滿足以上任一條件時，超出上限的資料将會按行級别被截掉并傳回下一行資料主鍵資訊。

API定義

message GetRangeRequest {
    required string table_name = 1;        // 表名
    required Direction direction = 2;        // 傳回順序
    repeated string columns_to_get = 3;        // 傳回列參數
    optional TimeRange time_range = 4;       // 傳回列版本号範圍
    optional int32 max_versions = 5;       // 傳回列版本個數
    optional int32 limit = 6;       // 單次請求傳回行數限制
    required bytes inclusive_start_primary_key = 7;       // 範圍請求起始主鍵
    required bytes exclusive_end_primary_key = 8;       // 範圍請求結束主鍵
    optional bytes filter = 10;       // 條件過濾
    optional string start_column = 11;       // 傳回屬性列列名起始
    optional string end_column = 12;       // 傳回屬性列列名結束
    optional bytes token = 13;       // 已廢棄
    optional string transaction_id = 14;       // 事務ID
}

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;       // Cu消耗統計
    required bytes rows = 2;       // 傳回的行資料結果
    optional bytes next_start_primary_key = 3;       // 翻頁辨別，下一頁起始主鍵
    optional bytes next_token = 4;       // 已廢棄
}

參數說明

table_name

表名，範圍讀接口僅對一張表做請求；

direction

方向或順序，範圍讀正序（主鍵由小到大）、倒序（主鍵由大到小）傳回，預設設定正序。

columns_to_get

傳回列名，傳回列的字段，支援全部列傳回。若指定列名但列不存在，整行資料不傳回（不代表行不存在）。

time_range

版本号範圍，屬性值版本号傳回範圍。

max_versions

版本号最大個數，屬性值版本傳回最大個數。

limit

單次請求行數限制，如果存在條件過濾或行資料較大，實際傳回行數可能小于參數，不代表後面沒有資料。要通過response中next_start_primary_key是否為空判斷。

範圍設定

邊界起、止都是完整的主鍵，代表特定的範圍位置。倒序時，起始主鍵需要大于結束主鍵。範圍包含如下兩個參數：

inclusive_start_primary_key：主鍵起始值（包含邊界）；
exclusive_end_primary_key：主鍵結束值（不包含邊界）；

filter

條件過濾器，可以提供列值的條件過濾篩選。支援列值的大于、小于、等于比較，以及多列字段的與或非混合條件。

寬行讀

指定列名範圍的讀取參數，字段按字元串序排列，基于範圍範圍範圍内屬性列。包含如下兩個參數：

start_column：屬性列的其實字段；
end_column：屬性列的終止字段；

transaction_id

事務ID，支援事務讀。範圍查詢請求是針對一個表的請求，如果資料範圍限制在一個分區鍵内，可以提供事務查詢能力。

功能與示例

最左比對

表中資料存儲基于PrimaryKey有序排列，主表是一個特殊的基于主鍵的聯合索引。是以，資料範圍查詢遵循聯合索引的最左比對原則。即：範圍查詢時如果某一列提供了具體的範圍值（非單值），則下一列的範圍限制限制是無效的。具體參考下圖：

Tablestore入門指南-GetRange範圍查詢詳解查詢接口參數說明功能與示例表格存儲使用手冊

上例中，第一列主鍵的起止不同，導緻第二列的限制未能生效，pk2=4的行也會出現在結果中。隻有目前一列的起始、終止參數一樣時，該列的起止限制條件才有效。如果使用者需要查詢pk2有限制範圍的所有行，應當考慮建立二級索引，将pk2作為索引的第一列主鍵。

連續翻頁

當範圍條件資料單次請求未拿到全量資料時，需要使用者基于NextStartPrimaryKey做連續翻頁，進而周遊全部命中資料。如果GetRangeResponse.getNextStartPrimaryKey()非空，則一定還有資料。通過将擷取的PrimaryKey設定到原請求中重新建構，然後再次發起請求。

注意：不可以通過行數等于零來判斷翻頁結束。

PrimaryKey nextStartPrimaryKey = null;
do {
    GetRangeResponse getRangeResponse = syncClient.getRange(getRangeRequest);
    List<Row> pageRowList = getRangeResponse.getRows();  // 判斷存在下一頁，重構請求

    nextStartPrimaryKey = getRangeResponse.getNextStartPrimaryKey();
    if (nextStartPrimaryKey != null) {                 // 判斷存在下一頁，重構請求
        criteria.setInclusiveStartPrimaryKey(nextStartPrimaryKey);
        getRangeRequest.setRangeRowQueryCriteria(criteria);
    }
} while (nextStartPrimaryKey != null);              // 持續翻頁，直到沒有下一頁

疊代器

為了友善使用者周遊全量資料，我們提供了疊代器接口。使用者無需關心請求建構、結果判斷等邏輯，隻需将異步Client與請求體作為參數建構GetRangeIterator即可。疊代器内部自動發起請求，消費完一頁資料後會自動發起下一頁請求；

AsyncClient asyncClient = (AsyncClient) syncClient.asAsyncClient();
GetRangeIterator getRangeIterator = new GetRangeIterator(asyncClient, getRangeRequest);

while (getRangeIterator.hasNext()) {
    Row row = getRangeIterator.next();
}

過濾器

表格存儲過濾器的過濾條件支援算術運算（=、!=、>、>=、<、<=）和邏輯運算（NOT、AND、OR），支援最多 10 個條件的組合。通過條件組合，限制列（含主鍵）屬性取值的限制。Limit限制的是過濾前的結果個數，經過過濾後實際傳回的結果可能小于limit甚至沒有資料。

SingleColumnValueFilter

單列的條件過濾參數。示例：Col0 == 0

SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
        SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
// 如果不存在 Col0 這一列, 也不傳回。

CompositeColumnValueFilter

組合多個算術運算符号達到多條件組合過濾的效果。示例：Col0 == 0 and Col1 >= 100

CompositeColumnValueFilter composite1 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.AND);
SingleColumnValueFilter single1 = new SingleColumnValueFilter("Col0",
      SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
SingleColumnValueFilter single2 = new SingleColumnValueFilter("Col1",
      SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100));
composite1.addFilter(single1);
composite1.addFilter(single2);

PassIfMissing

另外由于稀疏列的屬性，部分行的屬性列可能不存在，此時可以使用PassIfMissing參數來設定期望的過濾形式。

True：代表如果這一列不存在也傳回；
False：代表這一列不存在就不傳回。

示例：列不存在時不傳回

singleColumnValueFilter.setPassIfMissing(false);

表格存儲使用手冊

本文結合Java SDK的接口調用代碼，介紹了Tablestore在資料管理方面的基本功能與使用方式。代碼已開源在Tablestore-Examples項目中，使用者可以直接運作使用。基于樣例代碼與文章，新使用者能更簡單、更快速地上手Tablestore，歡迎新、老使用者使用與建議。

通過對基礎使用功能的持續輸出，我們将整理出一套完整的使用手冊（含可執行樣例），敬請期待。

專家服務

如有疑問或者需要更好的線上支援，歡迎加入釘釘群：“表格存儲公開交流群”。群内提供免費的線上專家服務，歡迎掃碼加入，群号：23307953

Tablestore入門指南-GetRange範圍查詢詳解查詢接口參數說明功能與示例表格存儲使用手冊