管理Hologres Catalog

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

Catalog提供了元数据信息,例如数据库、表、分区以及数据库或其他外部系统中存储的函数和信息。配置Hologres Catalog后,您可以在实时计算开发控制台直接读取Hologres元数据,无需再手动注册Hologres表,提高作业开发的效率且保证数据的正确性。本文为您介绍如何配置、查看及删除Hologres Catalog。

使用限制

  • 仅Flink 1.13及以上版本支持配置Hologres Catalog。

  • 不支持修改Catalog。

  • 仅Flink计算引擎VVR-6.0.1-Flink-1.15及以上版本支持建表时设置表属性。

  • 仅Flink计算引擎VVR-6.0.3-Flink-1.15及以上版本支持创建Catalog时配置默认参数以及修改Hologres表属性。

  • 实时计算Flink版仅支持读写Hologres内表,因此Hologres实例必须是独占实例,不支持Hologres共享集群实例

创建Hologres Catalog

支持UI与SQL命令两种方式配置Hologres Catalog,推荐使用UI方式配置Hologres Catalog。

UI方式(推荐)

  1. 进入数据管理页面。

    1. 登录实时计算管理控制台,单击目标工作空间操作列下的控制台

    2. 单击数据管理

  2. 单击创建Catalog,选择Hologres后,单击下一步

  3. 填写参数配置信息。

    重要

    Catalog创建完成后,以下配置信息都不支持修改。如果需要修改,您需要删除掉已创建的Catalog,重新进行创建。

    HiveUI

    参数

    说明

    是否必填

    备注

    catalogname

    Hologres Catalog名称。

    仅支持小写字母a-z和数字0-9,不含大写字母、中划线(-)、下划线(_)等特殊字符。

    endpoint

    Hologres的Endpoint地址。

    详情请参见实例配置

    username

    阿里云账号的AccessKey ID。

    详情请参见如何查看AccessKey ID和AccessKey Secret信息?

    说明
    • 为了避免您的AK信息泄露,建议您通过变量的方式填写password取值,详情请参见项目变量

    • 当前配置的AccessKey对应的用户需要能够访问对应的Hologres数据库,Hologres数据库权限请参见Hologres权限模型

    password

    阿里云账号的AccessSecret。

    dbname

    您访问Hologres的默认数据库名称。

    无。

  4. 单击确定

    创建完成后,元数据下即可查看新建的Catalog。

SQL方式

  1. 数据查询文本编辑区域,输入配置Hologres Catalog的命令。

    CREATE CATALOG <catalogname> WITH (
      'type' = 'hologres',
      'endpoint' = '<endpoint>', 
      'username' = '<AccessKey>',
      'password' = '<AccessSecret>',
      'dbname' = '<dbname>'
    );

    参数详情如下表所示。

    参数

    说明

    是否必填

    备注

    catalogname

    Hologres Catalog名称。

    仅支持小写字母a-z和数字0-9,不含大写字母、中划线(-)、下划线(_)等特殊字符。

    type

    类型。

    固定值为hologres。

    endpoint

    Hologres的Endpoint地址。

    详情请参见实例配置

    username

    阿里云账号的AccessKey。

    详情请参见如何查看AccessKey ID和AccessKey Secret信息?

    说明
    • 为了避免您的AK信息泄露,建议您通过变量的方式填写password取值,详情请参见项目变量

    • 当前配置的AccessKey对应的用户需要能够访问对应的Hologres数据库,Hologres数据库权限请参见Hologres权限模型

    password

    阿里云账号的AccessSecret。

    dbname

    您访问Hologres的默认数据库名称。

    无。

    ignore-non-persisted-options

    在使用Hologres Catalog时创建带有不可持久化选项的表时,是否忽略非可持久化选项。

    参数取值如下:

    • true(默认值):可以成功创建出表,而忽略所有非可持久化选项。

    • false:会报创建表失败的错误。

    说明

    Hologres Catalog表选项的可持久化意味着当再次从Catalog读取该表的相关信息时,可以重新获取您在DDL中定义的一致的信息。目前仅支持endpoint、username、password和dbname可持久化选项。

    其他Hologres连接器支持的参数

    在创建Catalog时可以填入一些参数,包括WITH参数,之后使用此Catalog中的表时,将会默认配置这些参数。

    仅Flink计算引擎VVR 6.0.3-Flink 1.15及以上版本支持。

    说明
    • 使用此功能,需要ignore-non-persisted-options参数配置为true。

    • Flink计算引擎VVR 6.0.3-Flink 1.15以下版本只能通过Hints为每张表分别进行参数的配置。

  2. 选中创建Catalog的代码后,单击左侧代码行数上的运行

    image..png

查看Hologres Catalog

Hologres Catalog配置成功后,您可以通过以下步骤查看Hologres元数据。

  1. 进入数据管理页面。

    1. 登录实时计算管理控制台

    2. 单击目标工作空间操作列下的控制台

    3. 单击数据管理

  2. Catalog列表页面,查看Catalog名称类型

    说明
    • 如果您需要查看目标Catalog下的数据库和表,请单击查看

    • 如果Schema为public,则表名称前面就省略了Schema的前缀,即直接显示tableName。

使用Hologres Catalog

说明
  • 如果Schema为public,在填写${schema_name.table_name}时,可以省略模式名称的前缀,直接填写tableName,即${table_name}。

  • 通过Hologres Catalog读取出来的表支持消费update数据,读取出来的Hologres表的ignoredelete属性默认为false,mutatetype属性默认为insertorupdate。ignoredelete和mutatetype属性含义详情请参见宽表Merge和局部更新功能

创建Hologres表

UI方式

  1. 进入数据管理页面。

    1. 登录实时计算管理控制台

    2. 单击目标工作空间操作列下的控制台

    3. 单击数据管理

  2. 单击目标Catalog名称对应操作列的查看

  3. 单击目标数据库名称对应操作列的查看

  4. 单击创建表

  5. 使用内置连接器连接页签,单击连接方式,选择表类型。

  6. 单击下一步

  7. 填写建表语句并配置相关参数信息。代码示例如下。

    CREATE TABLE `${catalog_name}`.`${db_name}`.`${table_name}` (
     id INT,
     name STRING
    ) WITH (
     'connector' = 'hologres'
    );
  8. 单击确定

SQL命令方式

  1. 数据查询文本编辑区域,输入以下建表语句。

    通常,有以下几种方式创建Hologres表:

    • 使用USE CATALOG HoloName命令直接引用Hologres数据服务。

      USE CATALOG ${catalog_name};
      CREATE TABLE `${db_name}`.`${schema_name.table_name}`(
        ...
       ) WITH (
         'connector' = 'hologres'
       );

      USE语法详情请参见USE语句

    • DDL语句中直接引用Hologres数据服务信息。

      CREATE TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` (
        ...
      ) WITH (
        'connector' = 'hologres'
      );
    • DDL语句中设置物理表属性。

      CREATE TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` (
        ...
      ) WITH (
        'connector' = 'hologres',
        'table_property.orientation' = 'column',
        'table_property.distribution_key' = 'a',
        'table_property.clustering_key' = 'b:desc',
        'table_property.bitmap_columns' = 'a,b',
        'table_property.segment_key' = 'c',
        'table_property.time_to_live_in_seconds' = '86400',
        'table_property.binlog.level' = 'replica',
        'table_property.binlog.ttl' = '86400'
      );
      说明
      • 在已注册的Hologres数据服务下创建表时,WITH参数中connector为必填参数,且取值为hologres。可省略endpoint等其他参数。

      • 在创建Hologres表时,在WITH参数中指定的物理表属性参数,部分属性无法修改。

      • Flink计算引擎VVR-6.0.3-Flink-1.15以下版本创建Hologres表时,在WITH参数中指定的物理表属性参数仅在首次建表时有效,不允许修改。如果您需要修改,则请到Hologres侧修改。Flink计算引擎VVR-6.0.3-Flink-1.15及以上版本支持修改Hologres物理表属性。

      • 目前不支持直接在Hologres表中添加或修改支持的WITH参数。对于这些参数,您可以通过SQL hints的方式在INSERT语句中添加或修改。

      • Flink计算引擎VVR-6.0.5-Flink-1.15及以上版本支持建表时设置列描述,对应的Hologres物理表也会继承相应的列描述。

  2. 选中建表语句,单击左侧代码行数上的运行

    image

创建Hologres表时,允许在WITH参数中设置物理表属性,合理的表属性设置可以有助于系统高效地组织和查询数据。当前支持的属性参数和使用示例如下表所示,其中以table_property. 为前缀的是物理表属性。

参数

使用示例

是否支持修改

table_property.orientation

'table_property.orientation' = 'row,column'

不支持修改

table_property.table_group

'table_property.table_group' = 'table_group_xxx'

table_property.distribution_key

'table_property.distribution_key' = 'a,b'

table_property.clustering_key

'table_property.clustering_key' = 'a,b:desc'

table_property.segment_key

'table_property.segment_key' = 'c,d'

table_property.bitmap_columns

'table_property.bitmap_columns' = 'a:on,b:off'

支持修改

table_property.dictionary_encoding_columns

'table_property.dictionary_encoding_columns' = 'a:on,b:off,c:auto'

table_property.time_to_live_in_seconds

'table_property.time_to_live_in_seconds' = '864000'

table_property.binlog.level

'table_property.binlog.level' = 'replica'

table_property.binlog.ttl

'table_property.binlog.ttl' = '86400'

enableTypeNormalization

'enableTypeNormalization' = 'true'

在使用Hologres Catalog创建表时,是否打开类型宽容模式,参数取值如下:

  • true:启用类型宽容模式,在创建Hologres物理表时,会使用类型归一化后精度更高的数据类型。目前类型归一化规则如下:

    • TINYINT、SMALLINT、INT和BIGINT归一化为BIGINT。

    • CHAR、VARCHAR和STRING归一化为STRING。

    • FLOAT和DOUBLE归一化为DOUBLE。

    • 其他数据类型按照原本的类型映射规则创建,详情请参见类型映射

      说明

      在数据类型发生修改时,归一化规则的生效方式如下:

      • SMALLINT修改为INT,两者的归一化类型都是BIGINT,视为修改成功,CTAS作业正常运行。

      • 从FLOAT改为BIGINT,两者的归一化类型分别为DOUBLE和BIGINT,属于不兼容的情况,会抛出异常。

  • false(默认值):根据类型映射正常创建Hologres物理表。

说明
  • 在CTAS等场景中,可能需要调整已有字段数据类型的精度。例如从VARCHAR(10)到VARCHAR(20)。

  • Flink计算引擎VVR 6.0.5-Flink 1.15以下版本,上游修改数据类型可能导致CTAS任务失败,只能重建目标表。

  • Flink计算引擎VVR 6.0.5-Flink 1.15以上版本支持类型宽容模式,在上游发生数据类型修改事件时,只要所修改类型与原类型的归一化类型相同,都视作修改成功。

  • 宽容模式应该在首次启动CTAS作业时开启,如果在首次启动时未开启宽容模式,需要删除下游表并且将作业无状态重启才能生效。

说明

当前支持的表属性与Hologres侧是一致的,Catalog侧仅是加上了table_property.前缀用以区分。参数详情请参见建表概述订阅Hologres Binlog

修改Hologres表

说明

仅Flink计算引擎VVR-6.0.5-Flink-1.15及以上版本支持修改表操作。

目前Hologres Catalog支持的修改表操作及示例如下:

  • 修改表属性

    ALTER TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` SET (
      'table_property.binlog.level' = 'replica',
      'table_property.binlog.ttl' = '64700'
    );
    说明

    仅部分表属性支持修改,详情参考创建Hologres表

  • 重命名表

    ALTER TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` 
    RENAME TO `${catalog_name}`.`${db_name}`.`${schema_name.new_table_name}`;
  • 增加列

    ALTER TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` 
    ADD <column_name> <column_datatype> COMMENT '<column_comment>';
  • 修改列名

    ALTER TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` 
    RENAME <old_column_name> TO <new_column_name>;
  • 修改列注释

    ALTER TABLE `${catalog_name}`.`${db_name}`.`${schema_name.table_name}` 
    MODIFY <column_name> <original_column_type> COMMENT '<new_column_comment>';

从Hologres表中读取数据

INSERT INTO ${other_sink_table}
SELECT ...
FROM `${catalog_name}`.`${db_name}`.`${schema_name.table_name}`

写入结果数据至Hologres表

INSERT INTO `${catalog_name}`.`${db_name}`.`${schema_name.table_name}`
SELECT ... 
FROM ${other_source_table}

作为CTAS的目标端Catalog

CREATE TABLE IF NOT EXISTS `${catalog_name}`.`${db_name}`.`${schema_name.table_name}`
WITH (
  'connector' = 'hologres'
) AS TABLE ${other_source_table};

CTAS支持在WITH参数中设置物理表属性,在创建目标表时,同时在表上设置对应的属性。具体支持的表属性参数详情,请参见创建Hologres表

当从源端同步数据过程中,为保证数据能够写入Hologres,Hologres Catalog会在以下情况被迫改写目标端的Schema:

  • 上游Schema使用DECIMAL类型的列作为主键。

    由于Hologres不支持DECIMAL类型作为主键,因此Hologre默认会改写该列类型为BIGINT。如果该改写不满足您的需求,则您也可以使用CTAS语法将引用的类转换为STRING类型,并重新建立主键。

  • 上游Schema中包含类型TIME、TIMESTAMP或TIMESTAMP_LTZ且精度大于6。

    由于Hologres支持的时间类型精度为6,因此为了确保数据能够写入到Hologres中,Flink会隐式地丢弃高于Hologres所支持的最高精度的部分。

作为CDAS的目标端Catalog

CREATE DATABASE IF NOT EXISTS `${catalog_name}`.`${db_name}`
WITH (
  'sink.parallelism' = '5' -- 设置每张结果表的并发数。
) AS DATABASE ${other_source_database};

在同步过程之中,您可以在WITH参数声明结果表的参数。当作业启动时,这些参数将被应用到需要同步的下游表中。具体可以调节的参数请参见实时数仓Hologres结果表

除了交互式Hologres结果表中支持的参数外,CDAS还支持在WITH参数中指定schemaname,将数据同步到Hologres目标库的指定Schema中。参数解释如下表所示。

参数

说明

是否必填

备注

schemaname

schema名称。

默认值为public。

说明

由于每张目标表可能需要设置不同的表属性,而WITH参数中不支持为每张表分别设置属性,因此CDAS不支持设置物理表属性。如果您需要设置表属性,则需要先手动创建目标表,再去启动CDAS作业。表属性参数详情请参见上文的创建Hologres表部分。

删除Hologres Catalog

UI方式

  1. 进入数据管理页面。

    1. 登录实时计算管理控制台

    2. 单击目标工作空间操作列下的控制台

    3. 单击数据管理

  2. Catalog列表页面,单击目标Catalog名称对应操作列下的删除

  3. 在弹出的对话框中,单击删除

    说明

    删除完成后,在左侧元数据区域下即可查看目标Catalog已删除。

SQL命令方式

  1. 数据查询文本编辑区域,输入以下命令。

    DROP CATALOG ${catalog_name}

    其中,catalog_name为您要删除的在实时计算开发控制台上显示的Hologres Catalog名称。

    警告

    删除Hologres Catalog不会影响已运行的作业,但对未上线或者需要暂停恢复的作业均产生影响,请您谨慎操作。

  2. 选中删除Catalog的命令,鼠标右键选择运行

  3. 在左侧元数据区域,查看目标Catalog是否已删除。