Todos os produtos
Search

Este produto

    Tablestore:Read rows with an iterator

    Central de documentação

    Tablestore:Read rows with an iterator

    Última atualização: Jul 08, 2026

    O Tablestore SDK for Java oferece um iterador para ler várias linhas em um intervalo de chave primária. Esse iterador emite solicitações paginadas automaticamente, recurso útil para varreduras de grandes intervalos que processam linhas individualmente.

    Pré-requisitos

    Instale o Tablestore SDK for Java e inicialize o cliente.

    Descrição

    public Iterator<Row> createRangeIterator(RangeIteratorParameter rangeIteratorParameter) throws TableStoreException, ClientException

    Crie um iterador sobre um intervalo de chave primária que retorne um Iterator<Row> padrão do Java. Cada chamada a iterator.next() retorna uma linha de um buffer interno e emite a próxima solicitação em lote quando o buffer está vazio. Não é necessário rastrear nextStartPrimaryKey nem iterar manualmente sobre getRange.

    O exemplo a seguir itera progressivamente pela tabela range_iter_demo, começa na chave primária row1 e continua até o final da tabela, imprimindo cada linha.

    String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

// End primary key (exclusive). INF_MAX reads to the end of the table.
PrimaryKeyBuilder endPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
endPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setExclusiveEndPrimaryKey(endPkBuilder.build());

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
int count = 0;
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
    count++;
}
System.out.println("Total rows iterated: " + count);

    Parâmetros

    Use RangeIteratorParameter para definir as condições da consulta de iteração. Os parâmetros estão descritos abaixo.

    Nome

    Tipo

    Descrição

    tableName (obrigatório)

    String

    Nome da tabela a ser lida.

    inclusiveStartPrimaryKey (obrigatório)

    PrimaryKey

    Chave primária inicial, incluindo nomes e valores das colunas de chave primária.

    • Os dados retornados incluem a chave primária inicial.

    • A quantidade e os tipos das colunas de chave primária devem corresponder ao esquema da tabela.

    • Na iteração progressiva, a chave primária inicial deve ser menor que a final. Na iteração regressiva, a chave primária inicial deve ser maior que a final.

    • Use PrimaryKeyValue.INF_MIN para infinito negativo e PrimaryKeyValue.INF_MAX para infinito positivo.

    exclusiveEndPrimaryKey (obrigatório)

    PrimaryKey

    Chave primária final, incluindo nomes e valores das colunas de chave primária.

    • Os dados retornados não incluem a chave primária final.

    • A quantidade e os tipos das colunas de chave primária devem corresponder ao esquema da tabela.

    • Use PrimaryKeyValue.INF_MIN para infinito negativo e PrimaryKeyValue.INF_MAX para infinito positivo.

    direction (opcional)

    Direction

    Direção da leitura.

    • FORWARD: valor padrão. Itera progressivamente.

    • BACKWARD: itera regressivamente.

    maxVersions (obrigatório, maxVersions ou timeRange)

    OptionalValue<Integer>

    Número máximo de versões retornadas por coluna de atributo. Defina pelo menos um entre maxVersions e timeRange.

    Se as versões correspondentes excederem esse máximo, o Tablestore retorna as mais recentes, da mais nova para a mais antiga, até atingir o limite definido.

    timeRange (obrigatório, maxVersions ou timeRange)

    OptionalValue<TimeRange>

    Intervalo de versões. Defina pelo menos um entre maxVersions e timeRange.

    Cada coluna de atributo pode conter várias versões. Definir um intervalo de versões retorna apenas os dados dentro desse período.

    maxCount (opcional)

    int

    Número total máximo de linhas retornadas pelo iterador. Deve ser maior que 0.

    bufferSize (opcional)

    int

    Quantidade de linhas buscadas por solicitação subjacente. Deve ser maior que 0.

    Reduza este valor para diminuir o pico de uso de memória durante varreduras extensas. Quando o lote atual se esgota, o iterador solicita automaticamente o próximo lote a partir de onde parou.

    columnsToGet (opcional)

    Set<String>

    Colunas a serem lidas. Podem ser colunas de chave primária ou de atributo.

    • Se columnsToGet não estiver definido, a linha inteira será retornada.

    • Caso columnsToGet esteja definido e uma linha não contenha nenhuma das colunas especificadas, null será retornado.

    filter (opcional)

    OptionalValue<Filter>

    Condição de filtro. Para mais informações, consulte Usar filtros.

    Ao definir tanto columnsToGet quanto filter, o columnsToGet seleciona as colunas primeiro e o filter avalia as linhas em seguida.

    Exemplos

    Iteração regressiva

    Use setDirection(Direction.BACKWARD) para iterar regressivamente. Nesse modo, a chave primária inicial deve ser maior que a chave primária final.

    String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);
parameter.setDirection(Direction.BACKWARD);

// For backward iteration, the start primary key must be greater than the end primary key.
PrimaryKeyBuilder startPkBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
startPkBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.INF_MAX);
parameter.setInclusiveStartPrimaryKey(startPkBuilder.build());

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

parameter.setMaxVersions(1);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

    Limitar o número total de linhas

    Use setMaxCount para restringir o total de linhas retornadas pelo iterador. Esse recurso é útil para leituras top-N e evita varreduras desnecessárias.

    String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Return at most 3 rows.
parameter.setMaxCount(3);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

    Otimizar memória com tamanho de lote

    Defina setBufferSize para controlar a quantidade de linhas buscadas por solicitação subjacente. Valores menores reduzem o pico de uso de memória durante varreduras extensas.

    String tableName = "range_iter_demo";

RangeIteratorParameter parameter = new RangeIteratorParameter(tableName);

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

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

parameter.setMaxVersions(1);
// Fetch 2 rows per underlying request.
parameter.setBufferSize(2);

Iterator<Row> iterator = client.createRangeIterator(parameter);
while (iterator.hasNext()) {
    Row row = iterator.next();
    System.out.println(row);
}

    Referências