Read data from a secondary index - Tablestore SDK for Java - Tablestore

Utilice Tablestore SDK for Java para leer datos a través de un índice secundario global o local.

Requisitos previos

Instale Tablestore SDK for Java e inicialice un cliente.

Descripción de la función

Un índice secundario reorganiza las columnas de clave principal y las columnas predefinidas de una tabla de datos para proporcionar una ruta de lectura alternativa. Una tabla de índices es de solo lectura. Contiene la clave principal del índice, las columnas de clave principal que Tablestore agrega automáticamente desde la tabla de datos y las columnas de atributos especificadas al crear el índice. Para recuperar una columna de atributos no incluida en la tabla de índices, utilice la clave principal de la tabla de datos devuelta para consultar dicha tabla. Para obtener más información, consulte Secondary indexes.

Al leer una tabla de índices, los nombres y el orden de las columnas de clave principal deben coincidir con el esquema de clave principal de la tabla de índices. Por ejemplo, suponga que una tabla de datos utiliza user_id y order_id como su clave principal, y que category se agrega como columna de índice. La siguiente tabla compara el orden completo de la clave principal en índices secundarios globales y locales.

Tipo de índice	Clave principal del índice especificada en la creación	Orden completo de la clave principal de la tabla de índices
Índice secundario global	`category`	`category`, `user_id` y `order_id`. Tablestore agrega las columnas de clave principal de la tabla de datos no especificadas a la clave principal del índice.
Índice secundario local	`user_id` y `category`	`user_id`, `category` y `order_id`. La primera columna de clave principal del índice debe ser igual a la primera columna de clave principal de la tabla de datos.

Importante

Cuando se crea un índice secundario global que incluye datos existentes, la tabla de índices no se puede leer hasta que los datos existentes se hayan compilado y sincronizado. Espere a que finalice la sincronización antes de leer la tabla de índices.

Llame a getRow para leer una fila mediante la clave principal completa de la tabla de índices.

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

Llame a getRange para leer datos dentro de un rango de claves principales de la tabla de índices.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

El siguiente ejemplo lee una fila del índice secundario global example_global_index mediante su clave principal completa y devuelve únicamente la columna de atributos status.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user-1"))
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.fromLong(101L))
        .build();

SingleRowQueryCriteria criteria =
        new SingleRowQueryCriteria("example_global_index", primaryKey);
criteria.addColumnsToGet("status");
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println(response.getRow());

Parámetros

Parámetros para leer una sola fila

GetRowRequest contiene el siguiente parámetro.

Nombre	Tipo	Descripción
rowQueryCriteria (obligatorio)	`SingleRowQueryCriteria`	Las condiciones para leer una sola fila.

Condiciones de lectura de una sola fila

rowQueryCriteria es del tipo SingleRowQueryCriteria y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
tableName (obligatorio)	`String`	El nombre de la tabla de índices.
primaryKey (obligatorio)	`PrimaryKey`	La clave principal completa de la fila en la tabla de índices. La clave principal debe contener las columnas de clave principal del índice especificadas durante su creación y las columnas de clave principal de la tabla de datos agregadas automáticamente por Tablestore. Los nombres y el orden de las columnas deben coincidir con el esquema de la tabla de índices.
columnsToGet (opcional)	`Set<String>`	Los nombres de las columnas de atributos que se devolverán. Puede especificar hasta 128 columnas. Si no se especifica este parámetro, se devuelven todas las columnas de atributos de la fila en la tabla de índices. Una columna de atributos no incluida en la tabla de índices no se devuelve y debe recuperarse desde la tabla de datos.
maxVersions (condicionalmente obligatorio)	`int`	El número máximo de versiones que se devolverán para cada columna de atributos. El valor debe ser mayor que 0. Un índice secundario conserva únicamente la versión más reciente. En la mayoría de los casos, establezca este parámetro en `1`. Especifique `maxVersions` o `timeRange`, pero no ambos.
timeRange (condicionalmente obligatorio)	`TimeRange`	El rango de marcas de tiempo de las versiones de columnas de atributos, en milisegundos. El rango es cerrado por la izquierda y abierto por la derecha. Especifique `timeRange` o `maxVersions`, pero no ambos.
filter (opcional)	`Filter`	Un filtro del lado del servidor. La fila no se devuelve si no cumple con la condición del filtro.
startColumn (opcional)	`String`	El nombre de la primera columna de atributos que se devolverá en orden lexicográfico. La columna especificada se incluye. Este parámetro está diseñado para leer filas anchas.
endColumn (opcional)	`String`	El nombre de la última columna de atributos en orden lexicográfico. La columna especificada se excluye. Este parámetro está diseñado para leer filas anchas.

Parámetros para leer un rango de filas

GetRangeRequest contiene el siguiente parámetro.

Nombre	Tipo	Descripción
rangeRowQueryCriteria (obligatorio)	`RangeRowQueryCriteria`	Las condiciones para leer un rango de filas.

Condiciones de lectura de rango

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

Nombre	Tipo	Descripción
tableName (obligatorio)	`String`	El nombre de la tabla de índices.
inclusiveStartPrimaryKey (obligatorio)	`PrimaryKey`	La clave principal inicial del rango. La clave principal se incluye en el resultado y debe contener todas las columnas de clave principal de la tabla de índices. Puede utilizar `INF_MIN` y `INF_MAX` para representar los valores mínimo y máximo de una columna de clave principal.
exclusiveEndPrimaryKey (obligatorio)	`PrimaryKey`	La clave principal final del rango. La clave principal se excluye del resultado y debe contener todas las columnas de clave principal de la tabla de índices. Puede utilizar `INF_MIN` y `INF_MAX` para representar los valores mínimo y máximo de una columna de clave principal.
direction (opcional)	`Direction`	La dirección de lectura. Los valores válidos son `FORWARD` y `BACKWARD`. Valor predeterminado: `FORWARD`. Para una lectura hacia adelante, la clave principal inicial debe ser menor que la clave principal final. Para una lectura hacia atrás, la clave principal inicial debe ser mayor que la clave principal final.
limit (opcional)	`int`	El número máximo de filas que se devolverán en una sola solicitud. El valor debe ser mayor que 0. El valor predeterminado es `-1`, lo cual indica que el cliente no limita el número de filas devueltas. El servidor devuelve un máximo de 5,000 filas y 4 MB de datos en una sola respuesta.
columnsToGet (opcional)	`Set<String>`	Los nombres de las columnas de atributos que se devolverán. Puede especificar hasta 128 columnas. Si no se especifica este parámetro, se devuelven todas las columnas de atributos de cada fila en la tabla de índices. Si ninguna de las columnas de atributos especificadas existe en una fila, dicha fila no se devuelve. Antes de consultar la tabla de datos, lea las columnas que existen en la tabla de índices o deje este parámetro sin especificar.
maxVersions (condicionalmente obligatorio)	`int`	El número máximo de versiones que se devolverán para cada columna de atributos. El valor debe ser mayor que 0. Un índice secundario conserva únicamente la versión más reciente. En la mayoría de los casos, establezca este parámetro en `1`. Especifique `maxVersions` o `timeRange`, pero no ambos.
timeRange (condicionalmente obligatorio)	`TimeRange`	El rango de marcas de tiempo de las versiones de columnas de atributos, en milisegundos. El rango es cerrado por la izquierda y abierto por la derecha. Especifique `timeRange` o `maxVersions`, pero no ambos.
filter (opcional)	`Filter`	Un filtro del lado del servidor. Solo se devuelven las filas que cumplen con la condición del filtro.
startColumn (opcional)	`String`	El nombre de la primera columna de atributos que se devolverá en orden lexicográfico. La columna especificada se incluye. Este parámetro está diseñado para leer filas anchas.
endColumn (opcional)	`String`	El nombre de la última columna de atributos en orden lexicográfico. La columna especificada se excluye. Este parámetro está diseñado para leer filas anchas.

Valores de retorno

Valores de retorno para la lectura de una sola fila

GetRowResponse contiene los siguientes parámetros de respuesta.

Nombre	Tipo	Descripción
row	`Row`	La fila devuelta. Si la fila no existe, se devuelve `null`.
consumedCapacity	`ConsumedCapacity`	Las unidades de capacidad consumidas por la operación.

Valores de retorno para la lectura de un rango de filas

GetRangeResponse contiene los siguientes parámetros de respuesta.

Nombre	Tipo	Descripción
rows	`List<Row>`	Las filas devueltas por la solicitud.
nextStartPrimaryKey	`PrimaryKey`	La clave principal inicial para la siguiente solicitud. Si este parámetro no es `null`, utilícelo como `inclusiveStartPrimaryKey` en la siguiente solicitud. Si este parámetro es `null`, significa que se han leído todas las filas del rango especificado. Este parámetro puede devolverse cuando una respuesta alcanza el límite del servidor, incluso si no se ha especificado `limit`.
consumedCapacity	`ConsumedCapacity`	Las unidades de capacidad consumidas por la operación.

Escenarios

Lectura de un rango de filas desde un índice secundario global

El siguiente ejemplo lee filas cuyo valor de category es books desde el índice secundario global example_global_index y gestiona el token de paginación nextStartPrimaryKey.

PrimaryKey startPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MIN)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey endPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MAX)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria rangeCriteria =
        new RangeRowQueryCriteria("example_global_index");
rangeCriteria.setInclusiveStartPrimaryKey(startPrimaryKey);
rangeCriteria.setExclusiveEndPrimaryKey(endPrimaryKey);
rangeCriteria.setMaxVersions(1);
rangeCriteria.setLimit(100);

List<Row> rows = new ArrayList<>();
while (true) {
    GetRangeResponse response =
            client.getRange(new GetRangeRequest(rangeCriteria));
    rows.addAll(response.getRows());

    if (response.getNextStartPrimaryKey() == null) {
        break;
    }
    rangeCriteria.setInclusiveStartPrimaryKey(
            response.getNextStartPrimaryKey());
}
rows.forEach(System.out::println);

Consulta de columnas de atributos en la tabla de datos

El siguiente ejemplo utiliza las rows devueltas en el ejemplo anterior. Extrae la clave principal de la tabla de datos de cada clave principal de la tabla de índices y consulta la columna de atributos detail en la tabla de datos example_table, la cual no está incluida en la tabla de índices.

for (Row indexRow : rows) {
    PrimaryKey indexPrimaryKey = indexRow.getPrimaryKey();
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(
                    "user_id",
                    indexPrimaryKey.getPrimaryKeyColumn("user_id").getValue())
            .addPrimaryKeyColumn(
                    "order_id",
                    indexPrimaryKey.getPrimaryKeyColumn("order_id").getValue())
            .build();

    SingleRowQueryCriteria rowCriteria =
            new SingleRowQueryCriteria("example_table", primaryKey);
    rowCriteria.addColumnsToGet("detail");
    rowCriteria.setMaxVersions(1);

    GetRowResponse response =
            client.getRow(new GetRowRequest(rowCriteria));
    System.out.println(response.getRow());
}