Read data from a secondary index - Tablestore SDK for Java - Tablestore: Central de Documentação do Alibaba Cloud

Pré-requisitos

Instale o Tablestore SDK for Java e inicialize um cliente.

Descrição do recurso

Um índice secundário reorganiza as colunas de chave primária e as colunas predefinidas de uma tabela de dados para oferecer um caminho alternativo de leitura. A tabela de índice é somente leitura. Ela contém a chave primária do índice, as colunas de chave primária que o Tablestore anexa automaticamente da tabela de dados e as colunas de atributo especificadas na criação do índice. Para recuperar uma coluna de atributo não incluída na tabela de índice, use a chave primária da tabela de dados retornada para consultar a tabela de dados. Para mais informações, consulte Secondary indexes.

Ao ler uma tabela de índice, os nomes e a ordem das colunas de chave primária devem corresponder ao esquema de chave primária dessa tabela. Por exemplo, suponha que uma tabela de dados use user_id e order_id como chave primária e que category seja adicionada como coluna de índice. A tabela a seguir compara a ordem completa da chave primária para índices secundários globais e locais.

Tipo de índice	Chave primária do índice especificada na criação	Ordem completa da chave primária da tabela de índice
Índice secundário global	`category`	`category`, `user_id` e `order_id`. O Tablestore anexa as colunas de chave primária da tabela de dados não especificadas à chave primária do índice.
Índice secundário local	`user_id` e `category`	`user_id`, `category` e `order_id`. A primeira coluna da chave primária do índice deve ser idêntica à primeira coluna da chave primária da tabela de dados.

Importante

Ao criar um índice secundário global que inclui dados existentes, a tabela de índice permanece indisponível para leitura até a compilação e sincronização desses dados. Aguarde a conclusão da sincronização antes de ler a tabela de índice.

Chame getRow para ler uma linha usando a chave primária completa da tabela de índice.

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

Chame getRange para ler dados dentro de um intervalo de chave primária da tabela de índice.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

O exemplo a seguir lê uma linha do índice secundário global example_global_index usando sua chave primária completa e retorna apenas a coluna de atributo 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 leitura de uma única linha

GetRowRequest contém o seguinte parâmetro.

Nome	Tipo	Descrição
rowQueryCriteria (obrigatório)	`SingleRowQueryCriteria`	Condições para leitura de uma única linha.

Condições de leitura de linha única

rowQueryCriteria é do tipo SingleRowQueryCriteria e contém os seguintes parâmetros.

Nome	Tipo	Descrição
tableName (obrigatório)	`String`	Nome da tabela de índice.
primaryKey (obrigatório)	`PrimaryKey`	Chave primária completa da linha na tabela de índice. Deve conter as colunas de chave primária do índice especificadas na criação e as colunas de chave primária da tabela de dados anexadas automaticamente pelo Tablestore. Os nomes e a ordem das colunas devem corresponder ao esquema da tabela de índice.
columnsToGet (opcional)	`Set<String>`	Nomes das colunas de atributo a retornar. É possível especificar até 128 colunas. Se este parâmetro não for definido, todas as colunas de atributo da linha na tabela de índice serão retornadas. Colunas de atributo não incluídas na tabela de índice não são retornadas; recupere-as diretamente da tabela de dados.
maxVersions (condicionalmente obrigatório)	`int`	Número máximo de versões a retornar para cada coluna de atributo. O valor deve ser maior que 0. Um índice secundário retém apenas a versão mais recente. Na maioria dos casos, defina este parâmetro como `1`. Especifique `maxVersions` ou `timeRange`, mas não ambos.
timeRange (condicionalmente obrigatório)	`TimeRange`	Intervalo de timestamp das versões da coluna de atributo, em milissegundos. O intervalo é fechado à esquerda e aberto à direita. Especifique `timeRange` ou `maxVersions`, mas não ambos.
filter (opcional)	`Filter`	Filtro no lado do servidor. A linha não será retornada se não atender à condição do filtro.
startColumn (opcional)	`String`	Nome da primeira coluna de atributo a retornar em ordem lexicográfica. A coluna especificada é incluída. Este parâmetro destina-se à leitura de linhas largas.
endColumn (opcional)	`String`	Nome da última coluna de atributo em ordem lexicográfica. A coluna especificada é excluída. Este parâmetro destina-se à leitura de linhas largas.

Parâmetros para leitura de um intervalo de linhas

GetRangeRequest contém o seguinte parâmetro.

Nome	Tipo	Descrição
rangeRowQueryCriteria (obrigatório)	`RangeRowQueryCriteria`	Condições para leitura de um intervalo de linhas.

Condições de leitura de intervalo

rangeRowQueryCriteria é do tipo RangeRowQueryCriteria e contém os seguintes parâmetros.

Nome	Tipo	Descrição
tableName (obrigatório)	`String`	Nome da tabela de índice.
inclusiveStartPrimaryKey (obrigatório)	`PrimaryKey`	Chave primária inicial do intervalo. Esta chave é incluída no resultado e deve conter todas as colunas de chave primária da tabela de índice. Use `INF_MIN` e `INF_MAX` para representar os valores mínimo e máximo de uma coluna de chave primária.
exclusiveEndPrimaryKey (obrigatório)	`PrimaryKey`	Chave primária final do intervalo. Esta chave é excluída do resultado e deve conter todas as colunas de chave primária da tabela de índice. Use `INF_MIN` e `INF_MAX` para representar os valores mínimo e máximo de uma coluna de chave primária.
direction (opcional)	`Direction`	Direção da leitura. Valores válidos: `FORWARD` e `BACKWARD`. Valor padrão: `FORWARD`. Para leitura direta, a chave primária inicial deve ser menor que a final. Para leitura reversa, a chave primária inicial deve ser maior que a final.
limit (opcional)	`int`	Número máximo de linhas a retornar em uma única solicitação. O valor deve ser maior que 0. O valor padrão é `-1`, indicando que o cliente não limita o número de linhas retornadas. O servidor retorna no máximo 5.000 linhas e 4 MB de dados por resposta.
columnsToGet (opcional)	`Set<String>`	Nomes das colunas de atributo a retornar. É possível especificar até 128 colunas. Caso este parâmetro não seja definido, todas as colunas de atributo de cada linha na tabela de índice serão retornadas. Se nenhuma das colunas de atributo especificadas existir em uma linha, essa linha não será retornada. Antes de consultar a tabela de dados, leia as colunas existentes na tabela de índice ou deixe este parâmetro sem especificação.
maxVersions (condicionalmente obrigatório)	`int`	Número máximo de versões a retornar para cada coluna de atributo. O valor deve ser maior que 0. Um índice secundário retém apenas a versão mais recente. Na maioria dos casos, defina este parâmetro como `1`. Especifique `maxVersions` ou `timeRange`, mas não ambos.
timeRange (condicionalmente obrigatório)	`TimeRange`	Intervalo de timestamp das versões da coluna de atributo, em milissegundos. O intervalo é fechado à esquerda e aberto à direita. Especifique `timeRange` ou `maxVersions`, mas não ambos.
filter (opcional)	`Filter`	Filtro no lado do servidor. Apenas as linhas que atenderem à condição do filtro serão retornadas.
startColumn (opcional)	`String`	Nome da primeira coluna de atributo a retornar em ordem lexicográfica. A coluna especificada é incluída. Este parâmetro destina-se à leitura de linhas largas.
endColumn (opcional)	`String`	Nome da última coluna de atributo em ordem lexicográfica. A coluna especificada é excluída. Este parâmetro destina-se à leitura de linhas largas.

Valores de retorno

Valores de retorno para leitura de uma única linha

GetRowResponse contém os seguintes parâmetros de resposta.

Nome	Tipo	Descrição
row	`Row`	Linha retornada. Se a linha não existir, `null` será retornado.
consumedCapacity	`ConsumedCapacity`	Unidades de capacidade consumidas pela operação.

Valores de retorno para leitura de um intervalo de linhas

GetRangeResponse contém os seguintes parâmetros de resposta.

Nome	Tipo	Descrição
rows	`List<Row>`	Linhas retornadas pela solicitação.
nextStartPrimaryKey	`PrimaryKey`	Chave primária inicial para a próxima solicitação. Se este parâmetro não for `null`, use-o como `inclusiveStartPrimaryKey` na próxima solicitação. Se for `null`, todas as linhas no intervalo especificado foram lidas. Este parâmetro pode ser retornado quando uma resposta atinge o limite do servidor, mesmo que `limit` não tenha sido especificado.
consumedCapacity	`ConsumedCapacity`	Unidades de capacidade consumidas pela operação.

Cenários

Leitura de um intervalo de linhas de um índice secundário global

O exemplo a seguir lê linhas cujo valor de category é books no índice secundário global example_global_index e processa o token de paginação 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 colunas de atributo na tabela de dados

O exemplo a seguir usa as rows retornadas no exemplo anterior. Ele extrai a chave primária da tabela de dados de cada chave primária da tabela de índice e consulta a tabela de dados example_table em busca da coluna de atributo detail, que não está incluída na tabela de índice.

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