表格存储 Java SDK 读取单行数据-表格存储 Tablestore(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());