管理Hologres Catalog

使用限制

• 仅Flink 1.13及以上版本支持配置Hologres Catalog。
• 不支持修改Catalog DDL。
• 仅Flink计算引擎VVR-6.0.1-Flink-1.15及以上版本支持建表时设置表属性。

配置Hologres Catalog

1. 登录实时计算管理控制台。
2. 在Flink全托管页签，单击目标工作空间操作列下的控制台。
3. 在左侧导航栏，单击作业开发。
4. 在页面左上角，单击新建，文件类型选择SQL。
5. 在文本编辑区域，输入配置Hologres Catalog的命令。

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

   catalogname为Hologres Catalog名称。仅支持小写字母a-z和数字0-9，不含大写字母、中划线（-）、下划线（_）等特殊字符。WITH参数详情如下表所示。

   参数	说明	是否必填
   type	类型，固定值为hologres。	是
   endpoint	Hologres的Endpoint地址。 详情请参见实例配置。	是
   username	阿里云账号的AccessKey。 说明 当前配置的AccessKey对应的用户需要能够访问所有的Hologres数据库，Hologres数据库权限请参见Hologres权限模型概述。	是
   password	阿里云账号的AccessSecret。	是
   dbname	您访问Hologres的默认数据库名称。	是
   ignore-non-persisted-options	在使用Hologres Catalog时创建带有不可持久化选项的表时，是否忽略非可持久化选项。参数取值如下： true（默认值）：可以成功创建出表，而忽略所有非可持久化选项。 false：会报创建表失败的错误。 说明 Hologres Catalog表选项的可持久化意味着当再次从Catalog读取该表的相关信息时，可以重新获取您在DDL中定义的一致的信息。目前仅支持endpoint、username、password和dbname可持久化选项。	否

6. 单击执行。
   执行完会提示Query has been executed。如果您需要删除Hologres Catalog，详情请参见删除Hologres Catalog。
7. 在左侧，单击Schemas页签。
8. 单击图标，刷新查看新建的Hologres Catalog。
   

查看Hologres Catalog

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

1. 登录实时计算管理控制台。
2. 在Flink全托管页签，单击目标工作空间操作列下的控制台。
3. 在左侧导航栏，单击作业开发。
4. 单击Schemas页签。
5. 在顶部菜单栏下拉框中，切换到目标Hologres Catalog名称，本文以holo为例。
   
6. 查看不同Hologres Catalog下的数据库、表和函数信息。
   

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

使用Hologres Catalog

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

  参数	使用示例
  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'

  说明 当前支持的表属性与Hologres侧是一致的，Catalog侧仅是加上了table_property. 前缀用以区分。参数详情请参见CREATE TABLE和订阅Hologres Binlog。
  通常，有以下几种方式使用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参数中指定的物理表属性参数，仅在首次建表时有效，不允许修改。如果您需要修改，则请到Hologres侧修改。
    • 目前不支持直接在Hologres表中添加或修改Hologres源表WITH参数、Hologres结果表WITH参数和Hologres维表WITH参数中支持的WITH参数。对于这些参数，您可以通过SQL hints的方式在INSERT语句中添加或修改。
• 从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 `${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

1. 登录实时计算管理控制台。
2. 在Flink全托管页签，单击目标工作空间操作列下的控制台。
3. 在左侧导航栏，单击作业开发。
4. 在页面左上角，单击新建，文件类型选择SQL。
5. 在文本编辑区域，输入以下命令。

   DROP CATALOG ${catalog_name}

   其中，catalog_name为您要删除的在Flink全托管开发控制台上显示的Hologres Catalog名称。

   说明 删除Hologres Catalog不会影响已运行的作业，但对未上线或者作业需要暂停恢复的作业，均产生影响，请您谨慎操作。
6. 单击执行。
7. 在左侧，单击Schemas页签。
8. 单击图标，刷新查看新建的Hologres Catalog是否已被删除。