Table Store Java SDK 讀取單行資料 - Tablestore

Java SDK 按主鍵讀取資料表中的單行資料，支援指定返回的屬性列、資料版本範圍和過濾條件，適用於按主鍵精確查詢單條記錄的情境。

前提條件

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

功能說明

public GetRowResponse getRow(GetRowRequest getRowRequest) throws TableStoreException, ClientException

按主鍵讀取資料表中的單行資料。通過 SingleRowQueryCriteria 指定查詢條件，結果通過 response.getRow() 擷取。

說明

必須設定 maxVersions 或 timeRange 至少其中一個，否則服務端會返回參數錯誤。

以下樣本從資料表 get_row_demo 讀取主索引值為 row1 的一行資料，僅返回每列最新版本。

String tableName = "get_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Read CU: " + response.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
System.out.println("Row: " + response.getRow());

關鍵參數：

tableName（必選）：讀取的資料表名稱。
primaryKey（必選）：主鍵資訊，必須包含全部主鍵列。
maxVersions 或 timeRange（二選一）：最大版本數或資料版本範圍。

參數說明

通過 SingleRowQueryCriteria 攜帶查詢條件，各參數說明如下。

名稱	類型	說明
tableName（必選）	String	讀取的資料表名稱。
primaryKey（必選）	PrimaryKey	主鍵資訊，包括主鍵列名稱和主索引值。主鍵列資料類型包括 STRING、INTEGER 和 BINARY。主鍵個數和類型必須與資料表的主鍵 schema 保持一致。主鍵列包含自增列時，也需要提供完整的主索引值（含自增列實際值）。
maxVersions（二選一）	OptionalValue<Integer>	最大版本數。`maxVersions` 和 `timeRange` 必須至少設定一個。如果符合查詢條件的資料版本數量超過設定的最大版本數，按從新到舊的順序返回指定版本數量的資料。
timeRange（二選一）	OptionalValue<TimeRange>	資料版本範圍。`maxVersions` 和 `timeRange` 必須至少設定一個。資料表的每個屬性列可以有不同的資料版本，設定版本範圍後僅返回該範圍內的資料。
columnsToGet（可選）	Set<String>	指定讀取的資料列，可以是主鍵列或屬性列。不設定 `columnsToGet` 時，返回整行資料。設定後如果讀取的行資料不包含任何指定的資料列，將返回 null。
filter（可選）	OptionalValue<Filter>	過濾條件，詳情請參見過濾器。如果同時設定 `columnsToGet` 和 `filter`，先按 `columnsToGet` 篩選資料列，再按 `filter` 條件過濾資料。

情境樣本

指定讀取的屬性列

通過 addColumnsToGet 指定要讀取的屬性列名，只返回這些列的資料。

String tableName = "get_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

// 唯讀取 col1 和 col2 兩列
criteria.addColumnsToGet("col1");
criteria.addColumnsToGet("col2");

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (selected columns): " + response.getRow());

指定資料版本範圍

通過 setTimeRange 指定版本時間區間，僅返回該範圍內的多版本資料。

String tableName = "get_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);

// 讀取過去一天內的所有版本資料
long now = System.currentTimeMillis();
criteria.setTimeRange(new TimeRange(now - 86400 * 1000L, now));
criteria.setMaxVersions(Integer.MAX_VALUE);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (time range): " + response.getRow());

條件過濾讀取

通過 setFilter 設定列值過濾條件，僅當行資料匹配條件時返回。

String tableName = "get_row_demo";

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
PrimaryKey primaryKey = primaryKeyBuilder.build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName, primaryKey);
criteria.setMaxVersions(1);

// 僅當 col1 等於 "val1" 時返回行
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
// 列不存在時不返回該行
filter.setPassIfMissing(false);
criteria.setFilter(filter);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println("Row (filtered): " + response.getRow());

Tablestore：讀取單行資料