动态列

如果您需要使用动态列功能，需要注意以下几点：

• 确保云原生多模数据库 Lindorm宽表引擎为2.2.19及以上版本，具体操作请参见升级小版本。

• Lindorm宽表中动态列类型均为VARBINARY，查询动态列和写入动态列时都必须将动态列类型转化成字节数组。

• 通过Lindorm SQL管理动态列，查询动态列和写入动态列操作支持以云数据库HBase兼容方式创建和写入的表。

动态列的开启可以通过以下两种方式：

• 在创建表格时通过WITH字句开启动态列功能。

  CREATE TABLE tablename (p1 INT, c1 INT, c2 VARCHAR, PRIMARY KEY(p1)) WITH (DYNAMIC_COLUMNS='true');

• 通过修改表的属性开启动态列功能。

  ALTER TABLE tablename SET 'DYNAMIC_COLUMNS' = 'true';

  说明

  开启动态列后，您可以修改表的属性或者在表的Schema中增加新的列，例如执行以下语句表示新增c3列，数据类型为INT。

  ALTER TABLE t_dynamic_columns ADD COLUMN c3 int;

  如果您在此之前写入c3动态列，由于写入的数据类型均为VARBINARY，查询数据和写入数据时会抛出IllegalDataException异常，所以变更动态列表的Schema时需要注意数据类型不同的情况。如果新增列的数据类型为VARBINARY就不会出现这个异常。

需要注意的是，以下示例尝试向表t_dynamic_columns中写入动态列c6，但由于指定的值gf不是HexString，所以该语句执行时报错。

UPSERT INTO t_dynamic_columns (p1, c6) VALUES (4, 'gf');

相较于上述直接通过SQL文本直接写动态列，更推荐的做法是在应用程序中通过SQL绑参的方式绑定要写入的字节数组实现写入。如果您需要将字符串或者数值型的值写入动态列中，那么需要先将这些值编码成字节数组，然后通过绑参写入。使用Java代码绑参写入动态列的代码示例如下：

Connection conn = DriverManager.getConnection(lindorm-jdbc-url);
String createTable = "CREATE TABLE testTable (p1 VARCHAR, c1 INT, PRIMARY KEY(p1)) 'DYNAMIC_COLUMNS' = 'true'";
Statement statement = conn.createStatement();
statement.execute(createTable);

//插入3列，其中p1，c1为Schema预先定义好的列，c2没有预先定义，为动态列写入。
String sqlUpsert = "upsert into " + tableName + "(p1, c1, c2) values(?, ?, ?)";
try (PreparedStatement stmt = conn.prepareStatement(sqlUpsert)) {
    stmt.setString(1, "pk");
    stmt.setInt(2, 4);
    stmt.setBytes(3, new byte[] {0,1});
    int updated = stmt.executeUpdate();
    Assert.assertEquals(1, updated);
}

查询动态列的场景分为以下几种：

• 查询字段为动态列。查询动态列表的语法与查询普通列表的语法一致，开启动态列之后，可以查询没有预先在Schema中定义的列，如下示例，c3和c4是创建表后新增的动态列。

  SELECT p1, c3, c4 FROM t_dynamic_columns WHERE p1 = 1;

  返回结果如下：

  +-----+-------+---------+
  | p1  |   c3  |   c4    |
  +-----+-------+---------+
  |  1  | 0x41  |  null   |
  +-----+-------+---------+
  1 rows in set (43 ms)

  重要

  由于动态列的类型是VARBINARY，Lindorm-cli会以HexString的形式展示查询结果，例如0x41表示字母A。

  如果期望查询结果以字符串的格式返回，您需要在启动Lindorm-cli时添加-bytesOutputAsString参数，语法如下：

  ./lindorm-cli -url <jdbc url> -username <用户名> -password <密码> -bytesOutputAsString

  此时，动态列的查询结果将转换为字符串类型。例如上述查询示例中的c3的值为A，再次查询上述语句的返回结果如下：

  +-----+-------+---------+
  | p1  |   c3  |   c4    |
  +-----+-------+---------+
  |  1  | A     |  null   |
  +-----+-------+---------+
  1 rows in set (43 ms)

• 使用SELECT *查询动态列表时，Lindorm SQL为了保证结果集元数据的正确性，需要在查询语句后加LIMIT。

  SELECT * FROM t_dynamic_columns LIMIT 10;

  返回结果如下：

  +-----+-------+---------+-------+------------+
  | p1  |   c1  |   c2    | c3    |     c4     |
  +-----+-------+---------+-------+------------+
  |  1  | null  |  1      | 0x41  | null       |
  |  2  | null  |  null   | null  | ?        |
  +-----+-------+---------+-------+------------+
  2 rows in set (141 ms)

  重要

  对于动态列表的SELECT *查询操作，LIMIT的默认最大值为5000，超过最大值会报错。

• 在WHERE条件中使用动态列。为了确保查询语句的性能WHERE条件中需包含主键或索引列，如果您使用Lindorm-cli或者使用SQL查询动态列时，那么查询语句中指定动态列的过滤条件也必须为HexString。

  接续上述的示例，例如表t_dynamic_columns的列c4为动态列，那么查询成功的语句如下示例：

  SELECT p1, c4 FROM t_dynamic_columns WHERE p1 >= 1 AND p1 < 3 AND c4 = 'ef0011';

  作为对比，下述查询示例中由于给动态列c4指定的过滤条件1不是一个HexString，所以该查询执行失败。

  SELECT p1, c1, c4 FROM t_dynamic_columns WHERE p1 = 2 AND c4 = '1';

在Java中，使用下述代码可以将字节数组转换为HexString。

private static final char[] DIGITS = {
  '0', '1', '2', '3', '4', '5', '6', '7',
  '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
  };

private static String toHexString(byte[] bytes) {
  char[] chars;
  int j = 0;
  chars = new char[bytes.length * 2];
  for (byte b : bytes) {
    chars[j++] = DIGITS[(b & 0xF0) >> 4];
    chars[j++] = DIGITS[b & 0x0F];
  }
  return new String(chars, 0, j);
}

public void testToHexString() {
  String s = "Hello, world";
  // 对于字符串类型，可以直接使用String的getBytes方法获得对象对应的byte[]
  byte[] bytes = s.getBytes(Charset.forName("UTF-8"));
  String hexString = toHexString(bytes);
  System.out.println(hexString); //打印结果为： 48656c6c6f2c20776f726c64
}