Table Store Java SDK 使用二級索引讀取資料 - Tablestore

使用 Java SDK 通過全域二級索引或本地二級索引讀取資料。

前提條件

安裝Tablestore Java SDK並初始化用戶端。

功能說明

二級索引通過重新組合資料表的主鍵列和預定義列，提供不同於資料表主鍵的讀取路徑。索引表只能用於讀取資料。索引表中包含索引主鍵、系統自動補充的資料表主鍵，以及建立索引時指定的屬性列；如需擷取索引表中未包含的屬性列，需根據返回的資料表主鍵反查資料表。關於二級索引的更多資訊，請參見二級索引。

讀取索引表時，主鍵列的名稱和順序必須與索引表的主鍵結構一致。例如，資料表以 user_id、order_id 為主鍵，二級索引使用 category 作為新增索引列時，兩類索引表的完整主鍵順序如下。

索引類型	建立索引時指定的索引主鍵	索引表的完整主鍵順序
全域二級索引	`category`	`category`、`user_id`、`order_id`。系統將未指定的資料表主鍵補充到索引主鍵末尾。
本地二級索引	`user_id`、`category`	`user_id`、`category`、`order_id`。第一列索引主鍵必須與資料表的第一列主鍵相同。

重要

建立全域二級索引並同步存量資料時，在存量資料構造和同步完成前不能讀取索引表。請等待存量資料同步完成後再讀取。

調用 getRow 根據完整的索引表主鍵讀取單行資料。

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

調用 getRange 按索引表主鍵範圍讀取資料。

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

以下樣本根據完整主鍵從全域二級索引 example_global_index 讀取一行資料，並僅返回 status 屬性列。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user-1"))
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.fromLong(101L))
        .build();

SingleRowQueryCriteria criteria =
        new SingleRowQueryCriteria("example_global_index", primaryKey);
criteria.addColumnsToGet("status");
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println(response.getRow());

參數說明

單行讀取參數

GetRowRequest 包含以下參數。

名稱	類型	說明
rowQueryCriteria（必選）	`SingleRowQueryCriteria`	單行讀取條件。

單行讀取條件

rowQueryCriteria 的類型為 SingleRowQueryCriteria，包含以下參數。

名稱	類型	說明
tableName（必選）	`String`	索引表名稱。
primaryKey（必選）	`PrimaryKey`	待讀取行的完整索引表主鍵。必須包含建立索引時指定的索引主鍵和系統自動補充的資料表主鍵，主鍵列的名稱和順序必須與索引表定義一致。
columnsToGet（可選）	`Set<String>`	需要返回的屬性列名稱，最多指定 128 列。不設定時返回索引表中該行的全部屬性列。索引表中未包含的屬性列不會返回，需反查資料表擷取。
maxVersions（條件必選）	`int`	每個屬性列最多返回的版本數，必須大於 0。二級索引僅保留最新版本，通常設定為 `1`。與 `timeRange` 至少設定一個，且不能同時設定。
timeRange（條件必選）	`TimeRange`	屬性列版本的時間戳記範圍，單位為毫秒，範圍為前閉後開區間。與 `maxVersions` 至少設定一個，且不能同時設定。
filter（可選）	`Filter`	服務端過濾條件。條件不匹配時不返回該行。
startColumn（可選）	`String`	返回屬性列的起始列名，按列名字典序排序，結果包含該列。主要用於寬行讀取。
endColumn（可選）	`String`	返回屬性列的結束列名，按列名字典序排序，結果不包含該列。主要用於寬行讀取。

範圍讀取參數

GetRangeRequest 包含以下參數。

名稱	類型	說明
rangeRowQueryCriteria（必選）	`RangeRowQueryCriteria`	範圍讀取條件。

範圍讀取條件

rangeRowQueryCriteria 的類型為 RangeRowQueryCriteria，包含以下參數。

名稱	類型	說明
tableName（必選）	`String`	索引表名稱。
inclusiveStartPrimaryKey（必選）	`PrimaryKey`	讀取範圍的起始主鍵，結果包含該主鍵。必須包含索引表的全部主鍵列。可使用 `INF_MIN` 和 `INF_MAX` 表示某一主鍵列的最小值和最大值。
exclusiveEndPrimaryKey（必選）	`PrimaryKey`	讀取範圍的結束主鍵，結果不包含該主鍵。必須包含索引表的全部主鍵列。可使用 `INF_MIN` 和 `INF_MAX` 表示某一主鍵列的最小值和最大值。
direction（可選）	`Direction`	讀取方向。取值為 `FORWARD` 或 `BACKWARD`，預設值為 `FORWARD`。正序讀取時起始主鍵必須小於結束主鍵；逆序讀取時起始主鍵必須大於結束主鍵。
limit（可選）	`int`	單次請求最多返回的行數，必須大於 0。預設值為 `-1`，表示不由用戶端限制返回行數；服務端單次最多返回 5000 行且資料大小不超過 4 MB。
columnsToGet（可選）	`Set<String>`	需要返回的屬性列名稱，最多指定 128 列。不設定時返回索引表中各行的全部屬性列。如果某行中指定的屬性列均不存在，則不返回該行；需要反查資料表時，應先讀取索引表中實際存在的列或不設定此參數。
maxVersions（條件必選）	`int`	每個屬性列最多返回的版本數，必須大於 0。二級索引僅保留最新版本，通常設定為 `1`。與 `timeRange` 至少設定一個，且不能同時設定。
timeRange（條件必選）	`TimeRange`	屬性列版本的時間戳記範圍，單位為毫秒，範圍為前閉後開區間。與 `maxVersions` 至少設定一個，且不能同時設定。
filter（可選）	`Filter`	服務端過濾條件，只返回滿足條件的行。
startColumn（可選）	`String`	返回屬性列的起始列名，按列名字典序排序，結果包含該列。主要用於寬行讀取。
endColumn（可選）	`String`	返回屬性列的結束列名，按列名字典序排序，結果不包含該列。主要用於寬行讀取。

傳回值

單行讀取傳回值

GetRowResponse 包含以下返回參數。

名稱	類型	說明
row	`Row`	返回的行資料。待讀取行不存在時返回 `null`。
consumedCapacity	`ConsumedCapacity`	本次操作消耗的服務能力單元。

範圍讀取傳回值

GetRangeResponse 包含以下返回參數。

名稱	類型	說明
rows	`List<Row>`	本次請求返回的行資料。
nextStartPrimaryKey	`PrimaryKey`	下一次讀取的起始主鍵。傳回值不為 `null` 時，將其作為下一次請求的 `inclusiveStartPrimaryKey` 繼續讀取；返回 `null` 時表示已讀取完指定範圍。即使未設定 `limit`，達到單次響應限制時仍會返回該參數。
consumedCapacity	`ConsumedCapacity`	本次操作消耗的服務能力單元。

情境樣本

按全域二級索引範圍讀取資料

以下樣本從全域二級索引 example_global_index 讀取 category 為 books 的資料，並處理分頁返回的 nextStartPrimaryKey。

PrimaryKey startPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MIN)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey endPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MAX)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria rangeCriteria =
        new RangeRowQueryCriteria("example_global_index");
rangeCriteria.setInclusiveStartPrimaryKey(startPrimaryKey);
rangeCriteria.setExclusiveEndPrimaryKey(endPrimaryKey);
rangeCriteria.setMaxVersions(1);
rangeCriteria.setLimit(100);

List<Row> rows = new ArrayList<>();
while (true) {
    GetRangeResponse response =
            client.getRange(new GetRangeRequest(rangeCriteria));
    rows.addAll(response.getRows());

    if (response.getNextStartPrimaryKey() == null) {
        break;
    }
    rangeCriteria.setInclusiveStartPrimaryKey(
            response.getNextStartPrimaryKey());
}
rows.forEach(System.out::println);

反查資料表擷取屬性列

以下樣本沿用上一樣本返回的 rows，從索引表主鍵中提取資料表主鍵，並反查資料表 example_table 擷取索引表中未包含的 detail 屬性列。

for (Row indexRow : rows) {
    PrimaryKey indexPrimaryKey = indexRow.getPrimaryKey();
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(
                    "user_id",
                    indexPrimaryKey.getPrimaryKeyColumn("user_id").getValue())
            .addPrimaryKeyColumn(
                    "order_id",
                    indexPrimaryKey.getPrimaryKeyColumn("order_id").getValue())
            .build();

    SingleRowQueryCriteria rowCriteria =
            new SingleRowQueryCriteria("example_table", primaryKey);
    rowCriteria.addColumnsToGet("detail");
    rowCriteria.setMaxVersions(1);

    GetRowResponse response =
            client.getRow(new GetRowRequest(rowCriteria));
    System.out.println(response.getRow());
}