Read a range of rows - Tablestore SDK for Java - Tablestore - Centro de documentación de Alibaba Cloud

Utilice Tablestore SDK for Java para leer filas consecutivas de una tabla del modelo Wide Column dentro de un rango de clave primaria.

Requisitos previos

Instale Tablestore SDK for Java e inicialice el cliente.

Descripción

Llame a getRange para leer filas consecutivas en orden ascendente o descendente dentro de un rango de clave primaria. Puede especificar las columnas devueltas, el rango de versiones de datos y las condiciones de filtro.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest) throws TableStoreException, ClientException

Nota

Una sola lectura por rango devuelve como máximo 5,000 filas o 4 MB de datos. Cuando se alcance cualquiera de estos límites, utilice nextStartPrimaryKey en la respuesta para continuar con la lectura.

El siguiente ejemplo realiza un escaneo ascendente en get_range_demo, lee todas las filas con una clave primaria mayor o igual que row1 y devuelve únicamente la versión más reciente de cada columna.

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));
for (Row row : response.getRows()) {
    System.out.println(row);
}

Parámetros

GetRangeRequest contiene los siguientes parámetros.

Nombre

Tipo

Descripción

rangeRowQueryCriteria (obligatorio)

RangeRowQueryCriteria

Los criterios para la lectura de un rango de filas.

transactionId (opcional)

String

El ID de transacción local. Establezca este parámetro solo cuando lea datos dentro de una transacción local.

Para obtener información sobre cómo obtener y utilizar el ID, consulte Use local transactions.

Criterios de consulta por rango

rangeRowQueryCriteria es de tipo RangeRowQueryCriteria y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
tableName (obligatorio)	`String`	El nombre de la tabla.
inclusiveStartPrimaryKey (obligatorio)	`PrimaryKey`	La clave primaria inicial inclusiva. Para lecturas ascendentes, debe ser menor que la clave primaria final. Para lecturas descendentes, debe ser mayor que la clave primaria final. Su esquema debe coincidir con el esquema de la tabla. Utilice `PrimaryKeyValue.INF_MIN` y `PrimaryKeyValue.INF_MAX` para representar infinito negativo y positivo, respectivamente.
exclusiveEndPrimaryKey (obligatorio)	`PrimaryKey`	La clave primaria final exclusiva. Su esquema debe coincidir con el esquema de la tabla. Utilice `PrimaryKeyValue.INF_MIN` y `PrimaryKeyValue.INF_MAX` para representar infinito negativo y positivo, respectivamente.
direction (opcional)	`Direction`	La dirección de lectura. El valor predeterminado es `FORWARD`. Establezca este parámetro en `BACKWARD` para realizar lecturas descendentes.
maxVersions (opcional)	`Integer`	El número máximo de versiones de datos que se devolverán para cada columna de atributo. Si hay más versiones coincidentes, Tablestore las devuelve de la más reciente a la más antigua. Establezca como mínimo uno de los parámetros `maxVersions` o `timeRange`.
timeRange (opcional)	`TimeRange`	El rango de versiones de datos. Solo se devuelven las versiones comprendidas en dicho rango. Establezca como mínimo uno de los parámetros `maxVersions` o `timeRange`.
limit (opcional)	`Integer`	El número máximo de filas que se devolverán en una sola llamada. El valor debe ser mayor que 0. Cuando se alcance el límite, utilice `nextStartPrimaryKey` en la respuesta para continuar con la lectura.
columnsToGet (opcional)	`Set<String>`	Las columnas que se devolverán. Si no especifica este parámetro, se devuelve la fila completa. Si lo especifica, no se devolverán las filas que no contengan ninguna de las columnas indicadas.
filter (opcional)	`Filter`	La condición de filtro. Si especifica tanto `columnsToGet` como `filter`, Tablestore selecciona primero las columnas a devolver y luego aplica el filtro. Para obtener información sobre cómo configurar el filtro, consulte Use filters.

Respuesta

GetRangeResponse contiene los siguientes campos específicos de la operación.

Campo	Tipo	Descripción
`rows`	`List<Row>`	Las filas devueltas en la llamada actual, obtenidas mediante `getRows`.
`nextStartPrimaryKey`	`PrimaryKey`	La clave primaria inicial para la siguiente llamada, obtenida mediante `getNextStartPrimaryKey`. Si ya se leyó el rango completo, se devuelve `null`.

Ejemplos de escenarios

Iteración paginada

nextStartPrimaryKey en la respuesta corresponde a la clave primaria inicial de la página siguiente. Llame a getRange en un bucle hasta que nextStartPrimaryKey sea nulo para escanear todas las filas coincidentes.

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

Escaneo descendente

Utilice setDirection(Direction.BACKWARD) para realizar un escaneo descendente. En este caso, la clave primaria inicial debe ser mayor que la clave primaria 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());

Filtrado condicional

Utilice setFilter para devolver únicamente las filas que cumplan con una condición de valor de columna.

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