Batch read rows

Prerequisites

Install Tablestore SDK for Java and initialize the client.

Description

Call batchGetRow to read multiple rows. Use one MultiRowQueryCriteria for each table. All rows in the same criteria share the version, returned-column, and filter settings.

The server processes each row independently. A failure on one row does not affect the other rows. Call isAllSucceed, getSucceedRows, and getFailedRows to inspect the results.

public BatchGetRowResponse batchGetRow(BatchGetRowRequest batchGetRowRequest) throws TableStoreException, ClientException

Note

A single batch read 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("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());
    }
}

Parameters

BatchGetRowRequest contains the following parameter.

Name	Type	Description
criteriasGroupByTable (required)	`Map<String, MultiRowQueryCriteria>`	The batch read criteria grouped by table. Add one `MultiRowQueryCriteria` for each table. All rows in the same criteria share the version, returned-column, and filter settings.

Per-table batch read criteria

Each value in criteriasGroupByTable is of the MultiRowQueryCriteria type and contains the following parameters.

Name	Type	Description
tableName (required)	`String`	The name of the table.
rowKeys (required)	`List<PrimaryKey>`	The primary keys of the rows to read, added by calling `addRow`. Each primary key must contain all primary key columns in the same order and with the same types as the table schema.
maxVersions (optional)	`Integer`	The maximum number of data versions to return for each attribute column. If more versions match, Tablestore returns versions from newest to oldest. Set at least one of `maxVersions` and `timeRange`.
timeRange (optional)	`TimeRange`	The data version range. Only versions in the range are returned. Set at least one of `maxVersions` and `timeRange`.
columnsToGet (optional)	`Set<String>`	The columns to return. If you do not specify this parameter, the entire row is returned. If you specify it and a row contains none of the specified columns, `row` in the row result is `null`.
filter (optional)	`Filter`	The filter condition. If you specify both `columnsToGet` and `filter`, Tablestore first selects the returned columns and then applies the filter. For information about how to configure the filter, see Use filters.

Response

BatchGetRowResponse contains the following operation-specific field.

Field	Type	Description
`tableToRowsResult`	`Map<String, List<RowResult>>`	The row-level results grouped by table, obtained by calling `getTableToRowsResult`. You can also call `getSucceedRows` and `getFailedRows` to obtain the successful and failed row results.

Row result

Each element in tableToRowsResult is of the RowResult type and contains the following fields.

Field	Type	Description
`isSucceed`	`boolean`	Indicates whether the row was read successfully.
`tableName`	`String`	The name of the table.
`row`	`Row`	The returned row. If the row does not exist or does not meet the filter condition, the value is `null`.
`error`	`Error`	The error information returned when the row fails to be read.
`index`	`int`	The position of the row in the corresponding `MultiRowQueryCriteria`.

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);