Read a range of rows - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Leia linhas consecutivas de uma tabela de dados dentro de um intervalo de chave primária com o Tablestore SDK for Java. Este recurso oferece suporte a varreduras diretas e reversas, filtragem por intervalo de versão e filtragem por valor de coluna.

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize um SyncClient (ou AsyncClient) antes de chamar getRange.

Descrição do recurso

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

Este método varre linhas consecutivas de uma tabela de dados dentro de um intervalo de chave primária. Especifique as chaves primárias inicial e final em RangeRowQueryCriteria e obtenha as linhas retornadas por meio de response.getRows().

O exemplo a seguir realiza uma varredura direta em get_range_demo, lendo todas as linhas com chave primária maior ou igual a row1 e retornando apenas a versão mais recente de cada coluna.

Nota

Uma única varredura de intervalo retorna no máximo 5.000 linhas ou 4 MB. Ao atingir esse limite, a resposta define nextStartPrimaryKey como a chave primária inicial da próxima página. Chame getRange em um loop para ler os dados restantes.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

// Start primary key (inclusive)
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

// End primary key (exclusive); INF_MAX denotes positive infinity
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("RequestId: " + response.getRequestId());
System.out.println("Read CU: " + response.getConsumedCapacity().getCapacityUnit().getReadCapacityUnit());
for (Row row : response.getRows()) {
    System.out.println(row);
}

Parâmetros

Transmita as condições de consulta por meio de RangeRowQueryCriteria. Os parâmetros estão descritos abaixo.

Name	Type	Description
tableName (required)	String	Nome da tabela de dados de leitura.
inclusiveStartPrimaryKey (required)	PrimaryKey	Chave primária inicial, contendo os nomes e valores das colunas de chave primária. Os dados retornados incluem a chave primária inicial. A quantidade e os tipos de colunas de chave primária devem corresponder ao esquema da tabela de dados. Em varreduras diretas, a chave primária inicial deve ser menor que a chave primária final. Em varreduras reversas, a chave primária inicial deve ser maior que a chave primária final. `PrimaryKeyValue.INF_MIN` representa infinito negativo e `PrimaryKeyValue.INF_MAX` representa infinito positivo.
exclusiveEndPrimaryKey (required)	PrimaryKey	Chave primária final, contendo os nomes e valores das colunas de chave primária. Os dados retornados excluem a chave primária final. A quantidade e os tipos de colunas de chave primária devem corresponder ao esquema da tabela de dados. `PrimaryKeyValue.INF_MIN` representa infinito negativo e `PrimaryKeyValue.INF_MAX` representa infinito positivo.
direction (optional)	Direction	Direção da varredura. `FORWARD` (padrão): varredura direta. `BACKWARD`: varredura reversa.
maxVersions (one of two)	OptionalValue<Integer>	Número máximo de versões. Obrigatório caso `timeRange` não esteja definido. Se os dados possuírem mais versões do que o valor de `maxVersions`, o Tablestore retorna as versões mais recentes em ordem decrescente.
timeRange (one of two)	OptionalValue<TimeRange>	Intervalo de versões. Obrigatório caso `maxVersions` não esteja definido. Colunas de atributo podem armazenar múltiplas versões. Ao definir um intervalo de versões, o Tablestore retorna apenas as versões compreendidas nesse intervalo.
limit (optional)	int	Quantidade máxima de linhas retornadas por chamada. O valor deve ser maior que 0. Caso os dados correspondentes excedam o valor de `limit`, a resposta conterá `limit` linhas, além da chave primária inicial para a próxima chamada.
columnsToGet (optional)	Set<String>	Colunas a serem lidas. Aceita colunas de chave primária ou colunas de atributo. Se `columnsToGet` não estiver definido, `getRange` retorna a linha inteira. Quando `columnsToGet` está definido e uma linha não contém nenhuma das colunas especificadas, essa linha é excluída da resposta.
filter (optional)	OptionalValue<Filter>	Condição de filtro. Para mais detalhes, consulte Filter. Ao configurar tanto `columnsToGet` quanto `filter`, o método `getRange` seleciona primeiro as colunas com `columnsToGet` e depois filtra as linhas com `filter`.

Exemplos de cenários

Iteração paginada

O campo nextStartPrimaryKey na resposta indica a chave primária inicial da próxima página. Chame getRange em um loop até que nextStartPrimaryKey seja nulo para varrer todas as linhas correspondentes.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

int totalRows = 0;
while (true) {
    GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
    totalRows += response.getRows().size();

    // The current response did not return all rows; use nextStartPrimaryKey to fetch the next page.
    PrimaryKey nextStart = response.getNextStartPrimaryKey();
    if (nextStart == null) {
        break;
    }
    criteria.setInclusiveStartPrimaryKey(nextStart);
}
System.out.println("Total rows scanned: " + totalRows);

Varredura reversa

Use setDirection(Direction.BACKWARD) para realizar a varredura em ordem inversa. Nesse caso, a chave primária inicial deve ser maior que a chave primária final.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);
criteria.setDirection(Direction.BACKWARD);

// For a reverse scan, the start primary key must be greater than the end primary key
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("row1"));
criteria.setExclusiveEndPrimaryKey(endPkBuilder.build());

criteria.setMaxVersions(1);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (backward): " + response.getRows().size());

Filtragem condicional

Use setFilter para retornar apenas as linhas que atendem a uma condição de valor de coluna.

String tableName = "get_range_demo";

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(tableName);

PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MIN);
criteria.setInclusiveStartPrimaryKey(startPkBuilder.build());

PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
criteria.setExclusiveEndPrimaryKey(endPkBuilder.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);

GetRangeResponse response = client.getRange(new GetRangeRequest(criteria));
System.out.println("Rows (filtered): " + response.getRows().size());

Tablestore:Read a range of rows