Tablestore入門手冊-資料管理-GetRow

GetRow接口概述

    GetRow接口用于讀取一行資料，是Tablestore最基礎的API之一。官方提供了Java、Go、Node.js、Python、PHP、C#、C++ SDK。

    本文以Java代碼為例，對GetRow接口進行詳細說明。

基本使用說明

參數說明

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

示例代碼

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);