Tablestore入門手冊-數據管理-GetRow

GetRow接口概述

GetRow接口用於讀取一行數據，是Tablestore最基礎的API之一。官方提供了Java、Go、Node.js、Python、PHP、C#、C++ SDK。
本文以Java代碼爲例，對GetRow接口進行詳細說明。

基本使用說明

參數說明

參數名稱	是否必填	參數說明
PrimaryKey	是	主鍵，所有主鍵都需要填寫
ColumnsToGet	否	需要讀取的列的集合，若不設置則讀取所有列
MaxVersions	MaxVersions 與 TimeRange 至少設置一個	最多讀取多少個版本
TimeRange	MaxVersions 與 TimeRange 至少設置一個	要讀取的版本範圍
Filter	否	過濾器，在服務端對讀取結果進行過濾

Java代碼示例

public void getRow() {
    //構造主鍵，主鍵列必須全部指定
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L));
    primaryKeyBuilder.addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"));
    PrimaryKey primaryKey = primaryKeyBuilder.build();

    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
    //設置讀取的版本數爲1，即讀取最新版本
    criteria.setMaxVersions(1);

    GetRowRequest getRowRequest = new GetRowRequest(criteria);
    GetRowResponse getRowResponse = syncClient.getRow(getRowRequest);
    Row row = getRowResponse.getRow();

    System.out.println("讀取行完畢, 結果爲: ");
    System.out.println(row);
}

多版本數據讀取

表格存儲支持多版本數據存儲，具體參考開發指南。

1.MaxVersions

指定maxVersions，返回最新的幾個版本。例如：某一行的某一列有20個歷史版本，設置maxVersions爲10，返回的是最新的10個版本。

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
// 設置讀取最新版本
criteria.setMaxVersions(10);

2.TimeRange

每一個版本都有一個對應的版本號，這個版本號默認是一個毫秒級的時間戳，用戶也可以自己指定版本號，讀取出來的時候可以按時間範圍取值，返回範圍內的版本列。

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
TimeRange timeRange = new TimeRange(1418380771, 1418390771);
criteria.setTimeRange(timeRange);

寬行讀取

有很多數據列的行，我們稱爲寬行。因爲數據列非常多，受網絡帶寬、延遲等因素的影響，我們無法一次性讀出來，這裏介紹幾種寬行的讀取方法。

1.使用ColumsToGet讀取指定列

ColumsToGet參數，允許用戶指定需要讀取的列。

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
// 設置讀取某些列
criteria.addColumnsToGet(new String[] {"Col1","Col2","Col3"});

2.使用startColumn，endColumn讀取一定範圍的屬性列

通過startColumn和endColumn指定寬行中某個範圍內的列，按照字典序對列進行排序比較。

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
criteria.setStartColumn("col0");
criteria.setEndColumn("col3");

3.使用ColumnPaginationFilter配合startColumn翻頁讀取

ColumnPaginationFilter有兩個參數，limit和offset，使用ColumnPaginationFilter讀取時，會跳過offset個屬性列，然後讀取limit個屬性列。配合startColumn使用時，會從startColumn開始，跳過offset個屬性列，讀取limit個屬性列。這種方式適合分頁讀取屬性列的場景。

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
// 設置從Column0開始讀
criteria.setStartColumn("Column0");
// 使用ColumnPaginationFilter設置一次要讀取的列數, limit=10, offset=0
criteria.setFilter(new ColumnPaginationFilter(10, 0));

使用過濾器

表格存儲過濾器的過濾條件支持算術運算（=、!=、>、>=、<、<=）和邏輯運算（NOT、AND、OR），支持最多 10 個條件的組合。過濾器的具體使用說明請參考：過濾器使用說明。

1.單條件過濾器：SingleColumnValueFilter

表格存儲中的數據是稀疏矩陣形式的，每一行的列可能都不一樣，對於不存在某一列的行，可以使用PassIfMissing參數來設置期望的過濾形式。passIfMissing爲True代表如果這一列不存在也返回，爲false代表這一列不存在就不返回。

// 設置過濾器, 當 Col0 的值爲 0 時返回該行。
SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
        SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
// 如果不存在 Col0 這一列, 也不返回。
singleColumnValueFilter.setPassIfMissing(false);

2.多條件過濾：CompositeColumnValueFilter

多條件過濾器，可以通過組合多個算術運算符號達到多條件組合過濾的效果。

// composite1 條件爲 (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);

// composite2 條件爲 ( (Col0 == 0) AND (Col1 > 100) ) OR (Col2 <= 10)
CompositeColumnValueFilter composite2 = new CompositeColumnValueFilter(CompositeColumnValueFilter.LogicOperator.OR);
SingleColumnValueFilter single3 = new SingleColumnValueFilter("Col2",
      SingleColumnValueFilter.CompareOperator.LESS_EQUAL, ColumnValue.fromLong(10));
composite2.addFilter(composite1);
composite2.addFilter(single3);