Batch read multiple rows - Tablestore SDK for Java - Tablestore

Prerequisites

Install Tablestore SDK for Java and initialize the client.

Description

public BatchGetRowResponse batchGetRow(BatchGetRowRequest batchGetRowRequest) throws TableStoreException, ClientException

Read multiple rows in a single request. A BatchGetRowRequest contains one or more MultiRowQueryCriteria objects added by calling addMultiRowQueryCriteria. Each MultiRowQueryCriteria targets one table. All rows in that criteria share the same query conditions, such as maxVersions, columnsToGet, and filter.

The server processes each row independently — a failure on one row does not affect the others. Call isAllSucceed, getSucceedRows, or getFailedRows to inspect row-level results.

Note

A single BatchGetRow call can retrieve up to 100 rows.

The following example reads two rows (primary keys row1 and row2) from the batch_get_demo table and returns only the most recent version of each column.

String tableName = "batch_get_demo";

MultiRowQueryCriteria criteria = new MultiRowQueryCriteria(tableName);

// Add primary key for row 1
PrimaryKeyBuilder pkb1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb1.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.addRow(pkb1.build());

// Add primary key for row 2
PrimaryKeyBuilder pkb2 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb2.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
criteria.addRow(pkb2.build());

criteria.setMaxVersions(1);

BatchGetRowRequest request = new BatchGetRowRequest();
request.addMultiRowQueryCriteria(criteria);

BatchGetRowResponse response = client.batchGetRow(request);
System.out.println("RequestId: " + response.getRequestId());
System.out.println("All Succeeded: " + response.isAllSucceed());

for (BatchGetRowResponse.RowResult rowResult : response.getSucceedRows()) {
    System.out.println("Succeeded: " + rowResult.getRow());
}
if (!response.isAllSucceed()) {
    for (BatchGetRowResponse.RowResult fail : response.getFailedRows()) {
        System.out.println("Failed: table=" + fail.getTableName()
                + " index=" + fail.getIndex()
                + " error=" + fail.getError());
    }
}

The required parameters are tableName, rowKeys, and one of maxVersions or timeRange. See the Parameters table for the full schema.

Parameters

A MultiRowQueryCriteria carries the batch query conditions for a single table.

Name	Type	Description
tableName (required)	String	The name of the table to read.
rowKeys (required)	List<PrimaryKey>	The list of primary keys, added by calling `addRow(PrimaryKey)`. All rows in this criteria share the same query conditions.
maxVersions (one required)	OptionalValue<Integer>	The maximum number of versions to read. Set at least one of `maxVersions` or `timeRange`. If a column has more versions than `maxVersions`, only the most recent versions are returned, up to `maxVersions`.
timeRange (one required)	OptionalValue<TimeRange>	The time range to read. Set at least one of `maxVersions` or `timeRange`. Each attribute column can have multiple versions. After you set a time range, Tablestore returns only the versions within that range.
columnsToGet (optional)	Set<String>	The columns to read — either primary key columns or attribute columns. If you do not set `columnsToGet`, Tablestore returns the entire row. If you set `columnsToGet` but the row contains none of the specified columns, Tablestore returns null.
filter (optional)	OptionalValue<Filter>	The filter condition. For details, see Filters. If you set both `columnsToGet` and `filter`, Tablestore first selects the columns specified in `columnsToGet`, then applies `filter` to the rows.

Scenarios

Read across multiple tables

To read from multiple tables in a single request, create one MultiRowQueryCriteria per table and add each one to the request with addMultiRowQueryCriteria.

String tableA = "batch_get_demo";
String tableB = "batch_get_demo_2";

BatchGetRowRequest request = new BatchGetRowRequest();

// Query conditions for table A
MultiRowQueryCriteria criteriaA = new MultiRowQueryCriteria(tableA);
PrimaryKeyBuilder pkA = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkA.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteriaA.addRow(pkA.build());
criteriaA.setMaxVersions(1);
request.addMultiRowQueryCriteria(criteriaA);

// Query conditions for table B
MultiRowQueryCriteria criteriaB = new MultiRowQueryCriteria(tableB);
PrimaryKeyBuilder pkB = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkB.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("rowA"));
criteriaB.addRow(pkB.build());
criteriaB.setMaxVersions(1);
request.addMultiRowQueryCriteria(criteriaB);

BatchGetRowResponse response = client.batchGetRow(request);
System.out.println("Total succeeded rows: " + response.getSucceedRows().size());

Read with a filter

Call setFilter to attach a column-value filter to the criteria. All rows in this MultiRowQueryCriteria use the same filter, and Tablestore returns only matching rows.

String tableName = "batch_get_demo";

MultiRowQueryCriteria criteria = new MultiRowQueryCriteria(tableName);

PrimaryKeyBuilder pkb1 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb1.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.addRow(pkb1.build());
PrimaryKeyBuilder pkb2 = PrimaryKeyBuilder.createPrimaryKeyBuilder();
pkb2.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row2"));
criteria.addRow(pkb2.build());

criteria.setMaxVersions(1);

// Return only rows where col1 equals "val1"
SingleColumnValueFilter filter = new SingleColumnValueFilter(
        "col1",
        SingleColumnValueFilter.CompareOperator.EQUAL,
        ColumnValue.fromString("val1"));
filter.setPassIfMissing(false);
criteria.setFilter(filter);

BatchGetRowRequest request = new BatchGetRowRequest();
request.addMultiRowQueryCriteria(criteria);

BatchGetRowResponse response = client.batchGetRow(request);
int matched = 0;
for (BatchGetRowResponse.RowResult rowResult : response.getSucceedRows()) {
    if (rowResult.getRow() != null) {
        matched++;
    }
}
System.out.println("Rows matching filter: " + matched);

Tablestore:Batch read rows