Use SQL to access HBase tables - Lindorm: Central de Documentação do Alibaba Cloud

Pré-requisitos

Antes de começar, verifique se você tem:

LindormTable versão 2.6.4 ou posterior. Para verificar ou atualizar sua versão, consulte Release notes of LindormTable e Upgrade the minor engine version of a Lindorm instance.

Funcionamento do mapeamento de colunas

As tabelas do HBase não possuem esquema fixo. As colunas armazenam bytes brutos (VARBINARY) e têm nomes dinâmicos. O recurso de mapeamento de colunas do LindormTable resolve essa diferença: declare o tipo de serialização Java usado na escrita de cada qualificador para que o Lindorm SQL decodifique os bytes e exponha as colunas como colunas SQL tipadas. Isso possibilita filtros WHERE, índices secundários e índices de pesquisa nos dados do HBase.

Para obter mais informações sobre colunas dinâmicas, consulte Colunas dinâmicas.

Sintaxe de mapeamento de colunas

Use ALTER TABLE para adicionar ou remover mapeamentos de colunas:

-- Add a mapping
ALTER TABLE <table_name> MAP DYNAMIC COLUMN [<family>:]<qualifier> <hbase_type>;

-- Remove one or more mappings
ALTER TABLE <table_name> UNMAP DYNAMIC COLUMN [<family>:]<qualifier> [, ...];

Valores de hbase_type compatíveis

Tipo	Tipo Java	Função de escrita	Quando usar
HLONG	java.lang.Long	`Bytes.toBytes(long)`	Dados escritos como `long` Java
HINTEGER	java.lang.Integer	`Bytes.toBytes(int)`	Dados escritos como `int` Java
HSHORT	java.lang.Short	`Bytes.toBytes(short)`	Dados escritos como `short` Java
HFLOAT	java.lang.Float	`Bytes.toBytes(float)`	Dados escritos como `float` Java
HDOUBLE	java.lang.Double	`Bytes.toBytes(double)`	Dados escritos como `double` Java
HSTRING	java.lang.String	`Bytes.toBytes(String)` — UTF-8	Dados escritos como `String` Java
HBOOLEAN	java.lang.Boolean	`Bytes.toBytes(boolean)`	Dados escritos como `boolean` Java

Importante

O tipo de mapeamento deve corresponder exatamente ao método de serialização Java usado na escrita. Incompatibilidades fazem o Lindorm SQL ler bytes incorretos e retornar resultados errados. Consulte Erros comuns abaixo.

Observações de uso

Adicionar um mapeamento declara o tipo da coluna, mas não exige dados pré-existentes nela.
O LindormTable 2.5.1 e versões posteriores aceitam mapeamentos de rowkey. Coloque o identificador rowkey entre crases: ` ROW `.
Em linguagens diferentes de Java, use o método toBytes da classe org.apache.hadoop.hbase.util.Bytes. Strings são sempre codificadas como UTF-8.

Erros comuns

Incompatibilidade entre tipo de mapeamento e caminho de escrita

Este é o risco mais crítico para a integridade dos dados. Se a coluna f:age foi escrita com Bytes.toBytes(int), mapeie-a como HINTEGER. Caso você a mapeie como HSTRING, o Lindorm SQL chamará Bytes.toString() sobre 4 bytes inteiros brutos e retornará dados inválidos.

Exemplo de mapeamento correto:

int age = 25;
put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age"), Bytes.toBytes(age));
// Map as HINTEGER

String age2 = "25";
put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age2"), Bytes.toBytes(age2));
// Map as HSTRING

Confundir esses tipos é a causa mais frequente de resultados incorretos em consultas.

Preparar dados de exemplo

Os passos abaixo utilizam a seguinte tabela e dados do HBase. Se já possuir uma tabela do HBase, pule para Mapear qualificadores de coluna.

O exemplo cria uma tabela chamada dt com a família de colunas f1 e grava uma linha usando a API do ApsaraDB for HBase para Java. Para usar o HBase Shell, consulte Usar o Lindorm Shell para conectar-se ao LindormTable.

// Create table dt with column family f1
try (Admin admin = connection.getAdmin()) {
    HTableDescriptor htd = new HTableDescriptor(TableName.valueOf("dt"));
    htd.addFamily(new HColumnDescriptor(Bytes.toBytes("f1")));
    admin.createTable(htd);
}

// Write one row
try (Table table = connection.getTable(TableName.valueOf("dt"))) {
    byte[] rowkey = Bytes.toBytes("row1");
    byte[] family = Bytes.toBytes("f1");
    Put put = new Put(rowkey);

    String name = "Some one";
    put.addColumn(family, Bytes.toBytes("name"), Bytes.toBytes(name));       // HSTRING

    int age = 25;
    put.addColumn(family, Bytes.toBytes("age"), Bytes.toBytes(age));         // HINTEGER

    long timestamp = 1656675491000L;
    put.addColumn(family, Bytes.toBytes("time"), Bytes.toBytes(timestamp));  // HLONG

    short buycode = 123;
    put.addColumn(family, Bytes.toBytes("buycode"), Bytes.toBytes(buycode)); // HSHORT

    float price = 12.3f;
    put.addColumn(family, Bytes.toBytes("price"), Bytes.toBytes(price));     // HFLOAT

    double price2 = 12.33333;
    put.addColumn(family, Bytes.toBytes("price2"), Bytes.toBytes(price2));   // HDOUBLE

    boolean isMale = true;
    put.addColumn(family, Bytes.toBytes("isMale"), Bytes.toBytes(isMale));   // HBOOLEAN

    table.put(put);
}

Mapear qualificadores de coluna

Conecte-se ao LindormTable usando o Lindorm-cli. Para obter instruções, consulte Usar o Lindorm-cli para conectar-se e utilizar o LindormTable.

Ao acessar uma tabela do HBase no ApsaraDB for HBase Performance-enhanced Edition, altere o formato da URL da API Java para jdbc:lindorm:table:url=http://<API URL for Java> e mude a porta de 30020 para 30060. Por exemplo, ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30020 torna-se jdbc:lindorm:table:url=http://ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30060 .

Mapeie o rowkey e todos os qualificadores para seus tipos correspondentes no Lindorm SQL:

ALTER TABLE dt MAP DYNAMIC COLUMN `ROW` HSTRING, f1:name HSTRING, f1:age HINTEGER, f1:time HLONG, f1:buycode HSHORT, f1:price HFLOAT, f1:price2 HDOUBLE, f1:isMale HBOOLEAN;

Verifique o mapeamento executando DESCRIBE:
```
DESCRIBE dt;
```
Para mais informações sobre a sintaxe DESCRIBE, consulte DESCRIBE/SHOW/USE.

Consulte a tabela:

SELECT * FROM dt LIMIT 1;
SELECT * FROM dt WHERE f1:isMale=true LIMIT 1;
SELECT * FROM dt WHERE f1:name='Some one' LIMIT 1;
SELECT * FROM dt WHERE f1:time>1656675490000 AND f1:time<1656675492000 LIMIT 1;

Criar índices (opcional)

Adicionar índices melhora o desempenho das consultas, mas exige armazenamento adicional. Escolha o tipo de índice conforme seu padrão de consulta:

Tipo de índice	Mais indicado para	Compensação
Índice secundário	Consultas em colunas sem chave primária com volume padrão de escrita	Leituras mais rápidas, maior uso de armazenamento e leve sobrecarga de escrita
Índice de pesquisa	Pesquisa de texto completo ou consultas complexas com múltiplas condições	Consultas flexíveis e custo de armazenamento mais elevado

Criar um índice secundário

Defina o atributo MUTABILITY da tabela:

Se escrever dados com timestamps personalizados, use MUTABLE_ALL em vez de MUTABLE_LATEST .
```
ALTER TABLE dt SET 'MUTABILITY' = 'MUTABLE_LATEST';
```

Crie o índice:

CREATE INDEX idx ON dt(f1:age) WITH (INDEX_COVERED_TYPE ='COVERED_DYNAMIC_COLUMNS');

Se especificou o parâmetro async e sua versão do LindormTable é anterior à 2.6.3, compile os dados históricos na tabela de índice:
```
BUILD INDEX idx ON dt;
```
Ignore esta etapa se não tiver usado async.

Verifique o índice:

SHOW INDEX FROM dt;

Saída esperada:

+---------------+-------------+-------------+--------------+------------------+---------------+-----------------+----------------+-------------+
| TABLE_SCHEMA  | DATA_TABLE  | INDEX_NAME  | INDEX_STATE  |  INDEX_PROGRESS  |  INDEX_TYPE   |  INDEX_COVERED  |  INDEX_COLUMN  |  INDEX_TTL  |
+---------------+-------------+-------------+--------------+------------------+---------------+-----------------+----------------+-------------+
| default       | dt          | idx         | ACTIVE       | 100%             | SECONDARY     |  TRUE           |  f1:age,ROW    |             |
+---------------+-------------+-------------+--------------+------------------+---------------+-----------------+----------------+-------------+

O índice estará pronto quando INDEX_STATE for ACTIVE. INDEX_PROGRESS mostra o progresso da compilação.

(Opcional) Verifique se a consulta usa o índice secundário:
```
EXPLAIN SELECT * FROM dt WHERE f1:age=23 LIMIT 1;
```
Para mais informações, consulte CREATE INDEX e Índices secundários.

Criar um índice de pesquisa

Crie o índice de pesquisa:
```
CREATE INDEX search_idx USING SEARCH ON dt(f1:age, f1:name);
```
Antes de criar um índice de pesquisa em uma tabela do HBase, observe o seguinte:
- Todas as colunas no índice de pesquisa já devem ter mapeamentos definidos.
- Os tipos de dados das colunas devem corresponder aos tipos de mapeamento compatíveis listados em Sintaxe de mapeamento de colunas.
- Não remova os mapeamentos de coluna após criar o índice de pesquisa, pois isso gera resultados de consulta incorretos.
- Ao escrever dados com timestamps personalizados, defina MUTABILITY como MUTABLE_ALL antes de criar o índice.

Verifique o status do índice:

SHOW INDEX FROM dt;

Saída esperada:

+--------------+------------+------------+-------------+----------------+------------+---------------+----------------+-----------+-------------------+
| TABLE_SCHEMA | DATA_TABLE | INDEX_NAME | INDEX_STATE | INDEX_PROGRESS | INDEX_TYPE | INDEX_COVERED |  INDEX_COLUMN  | INDEX_TTL | INDEX_DESCRIPTION |
+--------------+------------+------------+-------------+----------------+------------+---------------+----------------+-----------+-------------------+
| default      | dt         | idx        | ACTIVE      | DONE           | SECONDARY  | DYNAMIC       | f1:age,ROW     |           |                   |
| default      | dt         | search_idx | BUILDING    | N/A            | SEARCH     | NA            | f1:age,f1:name | 0         |                   |
+--------------+------------+------------+-------------+----------------+------------+---------------+----------------+-----------+-------------------+

Remover mapeamentos de colunas (opcional)

Remova um único mapeamento:

ALTER TABLE dt UNMAP DYNAMIC COLUMN f1:isMale;

Remova vários mapeamentos em uma única instrução:

ALTER TABLE dt UNMAP DYNAMIC COLUMN f1:price, f1:price2;

Lindorm:Use SQL to access an HBase table