語(yǔ)法

在Lindorm SQL中，對(duì)HBase表中自定義Column Family中的Qualifier添加映射，方便后續(xù)使用SQL進(jìn)行查詢。

添加和移除映射的語(yǔ)法如下：

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

其中，hbase_type可指定的映射數(shù)據(jù)類型如下表所示：

數(shù)據(jù)準(zhǔn)備

以HBase Java API為例，具體操作，請(qǐng)參見(jiàn)基于HBase Java API的應(yīng)用開(kāi)發(fā)。

//創(chuàng)建名為dt，family名為f1的HBase示例表           
try (Admin admin = connection.getAdmin()) {
            Table table = connection.getTable(TableName.valueOf("dt"));
            HTableDescriptor htd = new HTableDescriptor(TableName.valueOf("dt"));
            htd.addFamily(new HColumnDescriptor(Bytes.toBytes("f1")));
            admin.createTable(htd);
            }
    
//寫(xiě)入數(shù)據(jù)
try (Table table = connection.getTable(TableName.valueOf("dt"))) {
    byte[] rowkey = Bytes.toBytes("row1");
    byte[] family = Bytes.toBytes("f1");
    Put put = new Put(rowkey);
    //寫(xiě)入String類型,列名為name
    String name = "Some one";
    put.addColumn(family, Bytes.toBytes("name"), Bytes.toBytes(name));
    //寫(xiě)入Int類型，列名為age
    int age = 25;
    put.addColumn(family, Bytes.toBytes("age"), Bytes.toBytes(age));
    //寫(xiě)入Long類型，列名為time
    long timestamp = 1656675491000L;
    put.addColumn(family, Bytes.toBytes("time"), Bytes.toBytes(timestamp));
    //寫(xiě)入Short類型，列名為buycode
    short buycode = 123;
    put.addColumn(family, Bytes.toBytes("buycode"), Bytes.toBytes(buycode));
    //寫(xiě)入Float類型，列名為price
    float price = 12.3f;
    put.addColumn(family, Bytes.toBytes("price"), Bytes.toBytes(price));
    //寫(xiě)入Double類型，列名為price2
    double price2 = 12.33333;
    put.addColumn(family, Bytes.toBytes("price2"), Bytes.toBytes(price2));
    //寫(xiě)入Boolean類型，列名為isMale
    boolean isMale = true;
    put.addColumn(family, Bytes.toBytes("isMale"), Bytes.toBytes(isMale));

    //寫(xiě)入null值，所有類型寫(xiě)入空值null都表達(dá)為
    //put.addColumn(family, qualifier, null);

    table.put(put);
    }

操作步驟

以下以訪問(wèn)示例表dt為例，介紹如何使用SQL訪問(wèn)HBase表。

1. 通過(guò)Lindorm-cli連接并使用寬表引擎。具體操作，請(qǐng)參見(jiàn)通過(guò)Lindorm-cli連接并使用寬表引擎。

   說(shuō)明

   如果您在HBase增強(qiáng)版中使用SQL訪問(wèn)HBase表，需要將控制臺(tái)獲取的地址拼接成jdbc:lindorm:table:url=http://控制臺(tái)上獲取的Java API地址的形式，端口需要由30020修改為30060。

   例如：在控制臺(tái)上獲取的連接串地址為ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30020，轉(zhuǎn)換后的連接串地址為jdbc:lindorm:table:url=http://ld-bp1ietqp4fby3****-proxy-hbaseue.hbaseue.rds.aliyuncs.com:30060。

2. 使用ALTER TABLE語(yǔ)句對(duì)寫(xiě)入dt表的數(shù)據(jù)添加列映射。

   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;

   說(shuō)明

   • 添加列映射是指定列的數(shù)據(jù)類型，與是否寫(xiě)入數(shù)據(jù)無(wú)關(guān)。

   • 系統(tǒng)會(huì)根據(jù)Schema從Bytes中反解出原始數(shù)值，因此映射到Lindorm SQL時(shí)必須使用正確的數(shù)據(jù)類型。

   以下示例中，如果用戶把f:age2列的數(shù)據(jù)類型寫(xiě)為HINTEGER，系統(tǒng)調(diào)用Bytes.toInt()方法會(huì)反解出錯(cuò)誤的原始值。

   int age = 25;
   byte[] ageValue = Bytes.toBytes(age);
   put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age"), ageValue);//f:age列的數(shù)據(jù)類型為INT，映射到Lindorm SQL為HINTEGER類型。
   String age2 = "25";
   byte[] age2Value = Bytes.toBytes(age2);
   put.addColumn(Bytes.toBytes("f"), Bytes.toBytes("age2"), age2Value);//f:age2列的數(shù)據(jù)類型為STRING，映射到Lindorm SQL為HSTRING類型。

3. 通過(guò)DESCRIBE語(yǔ)句查看當(dāng)前Schema的映射關(guān)系。

   DESCRIBE dt;

   說(shuō)明

   DESCRIBE TABLE語(yǔ)法的詳細(xì)信息，請(qǐng)參見(jiàn)DESCRIBE/SHOW/USE。

4. 通過(guò)SQL語(yǔ)句查詢dt表中的數(shù)據(jù)。

   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. （可選）創(chuàng)建二級(jí)索引。

   二級(jí)索引是一種空間換時(shí)間的解決方案，它有利于提升非主鍵查詢模式的查詢效率，但需要占用一些存儲(chǔ)空間。關(guān)于二級(jí)索引的語(yǔ)法使用限制，請(qǐng)參見(jiàn)CREATE INDEX和二級(jí)索引。

   1. 修改主表dt的屬性。

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

      說(shuō)明

      如果使用了自定義時(shí)間戳，主表屬性需要設(shè)置為MUTABLE_ALL。

   2. 創(chuàng)建二級(jí)索引。

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

   3. 可選：如果您的寬表引擎版本小于2.6.3，創(chuàng)建二級(jí)索引時(shí)使用了async參數(shù)（異步構(gòu)建索引），您需要手動(dòng)將主表中的歷史數(shù)據(jù)構(gòu)建到索引表中。構(gòu)建完成后，才能通過(guò)二級(jí)索引查詢歷史數(shù)據(jù)。如果創(chuàng)建時(shí)沒(méi)有使用async參數(shù)，可跳過(guò)此步驟。

      BUILD INDEX idx ON dt;

   4. 查看索引。

      SHOW INDEX FROM dt;

      返回結(jié)果：

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

      說(shuō)明

      • 返回值中的INDEX_STATE的值為Active時(shí)，說(shuō)明數(shù)據(jù)構(gòu)建完成。

      • 返回值中PINDEX_PROGRESS的值表示索引構(gòu)建的進(jìn)度。

   5. 可選：使用EXPLAIN語(yǔ)句查看執(zhí)行計(jì)劃，可以查看是否命中二級(jí)索引。

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

6. 可選：創(chuàng)建搜索索引。已建立映射關(guān)系的表可以創(chuàng)建搜索索引，使用方式與Lindorm寬表的搜索索引一致，具體語(yǔ)法說(shuō)明請(qǐng)參見(jiàn)CREATE INDEX。關(guān)于搜索索引的特性和使用方法，請(qǐng)參見(jiàn)搜索索引。

   說(shuō)明

   如果您是通過(guò)SQL在HBase表上建立的搜索索引，各個(gè)搜索索引列需要注意以下限制：

   • 所有搜索索引列需要在列映射關(guān)系中定義。

   • 支持的數(shù)據(jù)類型與可映射的數(shù)據(jù)類型一致，具體說(shuō)明請(qǐng)參見(jiàn)映射數(shù)據(jù)類型。

   • 不能對(duì)搜索索引列解除映射，否則將導(dǎo)致查詢結(jié)果錯(cuò)誤。

7. 可選：刪除列映射。

   • 移除一個(gè)列映射。示例代碼如下：

     ALTER TABLE dt UNMAP DYNAMIC COLUMN f1:isMale;

   • 移除多個(gè)列映射。示例代碼如下：

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