Todos los productos
Search

Este producto

    Tablestore:Lectura de filas con un iterador

    Centro de documentos

    Tablestore:Lectura de filas con un iterador

    Última actualización: Sep 03, 2026

    El Tablestore SDK for Java permite leer filas dentro de un rango de clave primaria mediante un iterador y recuperar automáticamente los lotes siguientes.

    Requisitos previos

    Instale el Tablestore SDK for Java e inicialice el cliente.

    Descripción

    Llame al método createRangeIterator para crear un iterador de filas correspondiente a un rango de clave primaria específico. Cuando se agota el lote actual, el iterador emite automáticamente la siguiente solicitud. No es necesario rastrear nextStartPrimaryKey ni iterar sobre getRange.

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

    En el siguiente ejemplo se itera hacia adelante en la tabla range_iter_demo, comenzando en la clave primaria row1 y continuando hasta el final de la tabla, mientras se imprime cada fila.

    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

    Utilice RangeIteratorParameter para especificar las condiciones de consulta de la iteración. A continuación se describen los parámetros.

    Nombre

    Tipo

    Descripción

    tableName (obligatorio)

    String

    Nombre de la tabla que se va a leer.

    inclusiveStartPrimaryKey (obligatorio)

    PrimaryKey

    Clave primaria inicial, que incluye los nombres y valores de las columnas de clave primaria.

    • Los datos devueltos incluyen la clave primaria inicial.

    • La cantidad y los tipos de columnas de clave primaria deben coincidir con el esquema de la tabla.

    • Para una iteración hacia adelante, la clave primaria inicial debe ser menor que la clave primaria final. Para una iteración hacia atrás, la clave primaria inicial debe ser mayor que la clave primaria final.

    • Utilice PrimaryKeyValue.INF_MIN para infinito negativo y PrimaryKeyValue.INF_MAX para infinito positivo.

    exclusiveEndPrimaryKey (obligatorio)

    PrimaryKey

    Clave primaria final, que incluye los nombres y valores de las columnas de clave primaria.

    • Los datos devueltos no incluyen la clave primaria final.

    • La cantidad y los tipos de columnas de clave primaria deben coincidir con el esquema de la tabla.

    • Utilice PrimaryKeyValue.INF_MIN para infinito negativo y PrimaryKeyValue.INF_MAX para infinito positivo.

    direction (opcional)

    Direction

    Dirección de lectura.

    • FORWARD: valor predeterminado. Itera hacia adelante.

    • BACKWARD: itera hacia atrás.

    maxVersions (opcional)

    OptionalValue<Integer>

    Número máximo de versiones que se devuelven por columna de atributo. Debe establecer como mínimo uno de los siguientes parámetros: maxVersions o timeRange.

    Si las versiones coincidentes superan este máximo, Tablestore devuelve las versiones más recientes en orden de la más nueva a la más antigua, hasta alcanzar el límite máximo.

    timeRange (opcional)

    OptionalValue<TimeRange>

    Rango de versiones. Debe establecer como mínimo uno de los siguientes parámetros: maxVersions o timeRange.

    Cada columna de atributo puede contener varias versiones. Al configurar un rango de versiones, solo se devuelven los datos comprendidos dentro de dicho rango.

    maxCount (opcional)

    int

    Número total máximo de filas que devuelve el iterador. Debe ser mayor que 0.

    bufferSize (opcional)

    int

    Número de filas obtenidas por cada solicitud subyacente. Debe ser mayor que 0.

    Reduzca este valor para disminuir el uso máximo de memoria durante escaneos grandes. Cuando se agota el lote actual, el iterador solicita automáticamente el siguiente lote a partir del punto donde se quedó.

    columnsToGet (opcional)

    Set<String>

    Columnas que se van a leer. Pueden ser columnas de clave primaria o columnas de atributo.

    • Si no se establece columnsToGet, se devuelve la fila completa.

    • Si se establece columnsToGet y una fila no contiene ninguna de las columnas especificadas, se devuelve null.

    filter (opcional)

    OptionalValue<Filter>

    Condición de filtro. Para obtener más información, consulte Use filters.

    Si configura tanto columnsToGet como filter, primero se seleccionan las columnas mediante columnsToGet y luego filter evalúa las filas.

    Respuesta

    createRangeIterator devuelve un objeto Iterator<Row>. Llame a hasNext() para determinar si hay más datos disponibles y a next() para obtener el siguiente objeto Row.

    Ejemplos

    Iteración hacia atrás

    Utilice setDirection(Direction.BACKWARD) para iterar hacia atrás. En la iteración hacia atrás, la clave primaria inicial debe ser mayor que la clave primaria 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 el número total de filas

    Utilice setMaxCount para limitar el número total de filas que devuelve el iterador. Esta opción resulta útil para lecturas de los N primeros registros y evita escaneos innecesarios.

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

    Optimizar la memoria con el tamaño de lote

    Utilice setBufferSize para controlar el número de filas obtenidas por cada solicitud subyacente. Reduzca el valor para disminuir el uso máximo de memoria durante escaneos grandes.

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