ApsaraDB for HBase:Acesse tabelas do HBase usando SQL

Sintaxe

No Lindorm SQL, é possível adicionar mapeamentos a qualificadores em famílias de colunas personalizadas de uma tabela do HBase para facilitar consultas SQL.

A sintaxe para adicionar e remover mapeamentos é a seguinte:

dynamic_column_mapping_statement   := ALTER TABLE table_name MAP DYNAMIC COLUMN
                                      qualifer_definition hbase_type;
dynamic_column_unmapping_statement := ALTER TABLE table_name UNMAP DYNAMIC COLUMN
                                      qualifer_definition_list;
qualifer_definition_list           := qualifer_definition
                                      (',' qualifer_definition)*
qualifer_definition                := [ family_name ':' ] qualifier_name
hbase_type                         := HLONG | HINTEGER | HSHORT | HFLOAT |
                                      HDOUBLE | HSTRING | HBOOLEAN

A tabela a seguir descreve os tipos de dados de mapeamento que hbase_type pode especificar:

Preparação de dados

O exemplo a seguir utiliza a API Java do HBase. Para mais informações, consulte Use ApsaraDB for HBase API for Java to develop applications.

// Create the HBase sample table named "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 data
try (Table table = connection.getTable(TableName.valueOf("dt"))) {
    byte[] rowkey = Bytes.toBytes("row1");
    byte[] family = Bytes.toBytes("f1");
    Put put = new Put(rowkey);
    // Write a String value, column name "name"
    String name = "Some one";
    put.addColumn(family, Bytes.toBytes("name"), Bytes.toBytes(name));
    // Write an Int value, column name "age"
    int age = 25;
    put.addColumn(family, Bytes.toBytes("age"), Bytes.toBytes(age));
    // Write a Long value, column name "time"
    long timestamp = 1656675491000L;
    put.addColumn(family, Bytes.toBytes("time"), Bytes.toBytes(timestamp));
    // Write a Short value, column name "buycode"
    short buycode = 123;
    put.addColumn(family, Bytes.toBytes("buycode"), Bytes.toBytes(buycode));
    // Write a Float value, column name "price"
    float price = 12.3f;
    put.addColumn(family, Bytes.toBytes("price"), Bytes.toBytes(price));
    // Write a Double value, column name "price2"
    double price2 = 12.33333;
    put.addColumn(family, Bytes.toBytes("price2"), Bytes.toBytes(price2));
    // Write a Boolean value, column name "isMale"
    boolean isMale = true;
    put.addColumn(family, Bytes.toBytes("isMale"), Bytes.toBytes(isMale));

    // Write a null value. For all types, writing null is expressed as:
    //put.addColumn(family, qualifier, null);

    table.put(put);
    }

Procedimento

O exemplo abaixo utiliza a tabela de amostra dt para demonstrar como acessar uma tabela do HBase por meio de SQL.

1. Conecte-se ao mecanismo de tabela ampla usando o Lindorm-cli. Para mais informações, consulte Connect to and use the wide table engine with Lindorm-cli.

   Nota

   Se você usar SQL para acessar uma tabela do HBase no ApsaraDB for HBase Enhanced Edition, construa o endereço obtido no console no formato jdbc:lindorm:table:url=http://Java API address obtained in the console. Altere a porta de 30020 para 30060.

   Por exemplo, se o endereço da string de conexão obtido no console for ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30020, o endereço da string de conexão convertido será jdbc:lindorm:table:url=http://ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30060.

2. Use a instrução ALTER TABLE para adicionar mapeamentos de colunas aos dados gravados na tabela dt.

   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;

   Nota

   • Adicionar um mapeamento de coluna define o tipo de dado da coluna, independentemente de haver dados gravados.

   • O sistema decodifica o valor original de Bytes com base no esquema. Portanto, use o tipo de dado correto ao mapear para o Lindorm SQL.

   No exemplo a seguir, se o tipo de dado da coluna f:age2 for definido como HINTEGER, o sistema chamará o método Bytes.toInt() e retornará um valor original incorreto.

   int age = 25;
   byte[] ageValue = Bytes.toBytes(age);
   put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age"), ageValue);// The data type of column f:age is INT, and it is mapped to HINTEGER in Lindorm SQL.
   String age2 = "25";
   byte[] age2Value = Bytes.toBytes(age2);
   put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age2"), age2Value);// The data type of column f:age2 is STRING, and it is mapped to HSTRING in Lindorm SQL.

3. Use a instrução DESCRIBE para visualizar as relações de mapeamento do esquema atual.

   DESCRIBE dt;

   Nota

   Para mais informações sobre a sintaxe DESCRIBE TABLE, consulte DESCRIBE/SHOW/USE.

4. Consulte os dados na tabela dt usando uma instrução SQL.

   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;

5. (Opcional) Crie um índice secundário.

   Um índice secundário troca espaço por tempo. Ele melhora a eficiência de consultas em padrões que não usam chave primária, mas ocupa algum espaço de armazenamento. Para mais informações sobre a sintaxe e limites de uso de índices secundários, consulte CREATE INDEX e Secondary indexes.

   1. Modifique as propriedades da tabela primária dt.

      ALTER TABLE dt SET 'MUTABILITY' = 'MUTABLE_LATEST';

      Nota

      Se forem usados timestamps personalizados, defina a propriedade da tabela primária como MUTABLE_ALL.

   2. Crie o índice secundário:

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

   3. Opcional: Se a versão do seu mecanismo de tabela ampla for anterior à 2.6.3 e você usar o parâmetro async (construção assíncrona de índice) ao criar um índice secundário, construa manualmente os dados históricos da tabela primária na tabela de índice. Após a conclusão da construção, será possível consultar os dados históricos usando o índice secundário. Caso o parâmetro async não tenha sido usado durante a criação, pule esta etapa.

      BUILD INDEX idx ON dt;

   4. Visualize o índice.

      SHOW INDEX FROM dt;

      Resultado:

      +---------------+----------- -+-------------+--------------+------------------+---------------+-----------------+----------------+-------------+
      | 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    |             |
      +---------------+-------------+-------------+--------------+------------------+---------------+-----------------+----------------+-------------+

      Nota

      • Quando INDEX_STATE no valor de retorno for Active, a construção dos dados estará concluída.

      • PINDEX_PROGRESS no valor de retorno indica o progresso da construção do índice.

   5. Opcional: Use a instrução EXPLAIN para visualizar o plano de execução e verificar se um índice secundário foi utilizado.

      EXPLAIN SELECT * FROM dt WHERE f1:age=23 LIMIT 1;

6. Opcional: Crie um índice de pesquisa.

   1. Crie um índice de pesquisa.

      CREATE INDEX search_idx USING SEARCH ON dt(f1:age,f1:name);

      Nota

      Ao criar um índice de pesquisa em uma tabela do HBase usando SQL, observe os seguintes limites para cada coluna do índice de pesquisa:

      • Todas as colunas do índice de pesquisa devem estar definidas no mapeamento de colunas.

      • Os tipos de dados suportados são consistentes com os tipos de dados mapeáveis. Para mais informações, consulte Mapping data types.

      • Não é possível remover o mapeamento de uma coluna de índice de pesquisa. Caso contrário, os resultados da consulta estarão incorretos.

      • Se você usar timestamps personalizados para gravar na tabela do HBase e precisar criar um índice de pesquisa, defina a propriedade MUTABILITY da tabela como MUTABLE_ALL.

   2. Verifique se o índice foi criado com sucesso.

      SHOW INDEX FROM dt;

      Resultado:

      +--------------+------------+------------+-------------+----------------+------------+---------------+----------------+-----------+-------------------+
      | 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         |                   |
      +--------------+------------+------------+-------------+----------------+------------+---------------+----------------+-----------+-------------------+

7. Opcional: Remova mapeamentos de colunas.

   • Remova um único mapeamento de coluna. Exemplo:

     ALTER TABLE dt UNMAP DYNAMIC COLUMN f1:isMale;

   • Remova vários mapeamentos de colunas. Exemplo:

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