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