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

Java SDK 可按完整主鍵讀取寬表模型資料表中的一行資料。

前提條件

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

功能說明

調用 getRow 按完整主鍵讀取一行資料，可指定返回列、資料版本範圍和過濾條件。

public GetRowResponse getRow(GetRowRequest getRowRequest) throws TableStoreException, ClientException

說明

必須設定 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("Row: " + response.getRow());

參數說明

GetRowRequest 包含以下參數。

名稱

類型

說明

rowQueryCriteria（必選）

SingleRowQueryCriteria

單行讀取條件。

transactionId（可選）

String

局部事務 ID。僅在局部事務內讀取資料時設定。

關於如何擷取和使用該 ID，請參見局部事務。

單行讀取條件

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

名稱	類型	說明
tableName（必選）	`String`	資料表名稱。
primaryKey（必選）	`PrimaryKey`	行主鍵。必須包含資料表的全部主鍵列，且列名稱、順序和類型必須與資料表的主鍵結構一致。主鍵列支援 `STRING`、`INTEGER` 和 `BINARY` 類型；包含自增主鍵列時，必須傳入實際值。
maxVersions（可選）	`Integer`	最多返回的資料版本數。如果合格資料版本數超出該值，按版本號碼從新到舊返回。`maxVersions` 和 `timeRange` 必須至少設定一個。
timeRange（可選）	`TimeRange`	資料版本範圍。僅返回該範圍內的資料版本。`maxVersions` 和 `timeRange` 必須至少設定一個。
columnsToGet（可選）	`Set<String>`	要返回的列名稱。不設定時返回整行；設定後，如果行中不包含任何指定列，則返回 `null`。
filter（可選）	`Filter`	過濾條件。同時設定 `columnsToGet` 和 `filter` 時，先篩選返回列，再對結果應用過濾條件。關於過濾條件的配置方法，請參見過濾器。

傳回值

GetRowResponse 包含以下業務欄位。

欄位	類型	說明
`row`	`Row`	查詢到的行資料，通過 `getRow` 擷取。指定主鍵的行不存在或不滿足過濾條件時返回 `null`。

情境樣本

指定讀取的屬性列

通過 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());