Hologres对接DLF Paimon Catalog_数据湖构建(DLF)-阿里云帮助中心

Hologres自V3.2版本开始，支持通过DLF访问Paimon Catalog数据，为用户提供统一界面，提升元数据管理效率。

特色功能

支持通过External Database对接DLF中的Paimon Catalog，详情请参见EXTERNAL DATABASE。
- 支持通过Create/Drop External Schema实现级联创建/删除Paimon Catalog中的Database。
- 支持通过Create/Drop External Table实现级联创建/删除Paimon Catalog中的表。
- 支持查看Paimon Catalog中的所有Database和表。
支持使用Dynamic Table全量、增量读取Paimon表数据，详情请参见CREATE DYNAMIC TABLE。
支持使用ANALYZE、AUTO ANALYZE收集外部表统计信息，帮助优化器生成最佳的查询计划，详情请参见ANALYZE和AUTO ANALYZE。
支持外部表数据镜像。
TimeTravel：支持基于Timestamp、Version、Tag查询Paimon表历史快照。
分支查询：支持基于Branch查询Paimon分支数据及历史快照。
支持查询Paimon系统表，如Snapshots、Tags。

前提条件

已开通2.5及以上版本的DLF服务并新建Paimon Catalog。详情请参见授权并开通DLF和数据目录。
已购买Hologres实例并开通数据湖加速服务，且要求与DLF服务位于同一地域。详情请参见环境配置。

使用限制

不支持写入 Paimon 表（包括 INSERT、UPDATE、DELETE、TRUNCATE 等操作）。
仅通过 External Database 映射的 Paimon 外表支持 TimeTravel 查询、Branch 查询和数据镜像功能。
不支持对发生 Schema Evolution 的表或 Dynamic Table 执行 TimeTravel 查询。
外部表镜像不支持 Paimon 主键表。
不支持读取 Paimon 表中分区值为 NULL 或空的默认分区数据。
不支持通过 HoloWeb 的 OSS 数据湖加速功能可视化创建 DLF Paimon Catalog。
只读从实例不支持开启数据湖加速能力。

使用External Database方式映射Paimon Catalog

SLR模式

服务关联角色（SLR）是一种可信实体为阿里云服务的RAM角色，旨在解决跨云服务的授权访问问题。多数情况下，当您使用特定功能时，关联的云服务会自动创建或删除服务关联角色，不需要您手动创建或删除。通过服务关联角色可以更好地配置云服务正常操作所必需的权限，避免误操作带来的风险。详情请参见服务关联角色。

适用场景

SLR模式适用于使用当前用户身份访问External Database数据的场景，Hologres默认基于SLR和身份透传实现跨云产品访问。

操作步骤

连接Hologres实例并创建External Database。

CREATE EXTERNAL DATABASE <ext_database_name> WITH
  catalog_type 'paimon'
  metastore_type 'dlf-rest'
  dlf_catalog '<dlf_catalog_name>' 
  comment 'paimon catalog on dlf'
  ;

查看External Database下的Schema和表。

-- 查询External Database下的Schema
SELECT * FROM hologres.hg_external_schemas('<ext_database_name>');

-- 查询Schema下的表
SELECT * FROM hologres.hg_external_tables ('<ext_database_name>', '<ext_schema_name>');

查询表数据。

SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

STS模式

阿里云STS（Security Token Service）是阿里云提供的一种临时访问权限管理服务。RAM提供RAM用户和RAM角色两种身份。其中，RAM角色不具备永久身份凭证，而只能通过STS获取可以自定义时效和访问权限的临时身份凭证，即安全令牌（STS Token），详情请参见什么是STS。

适用场景

STS模式适用于跨账号访问和Hologres自定义账号（BASIC账号）访问External Database数据的场景。

操作步骤

登录RAM控制台，创建RAM角色，并授予DLF访问权限AliyunDLFFullAccess或AliyunDLFReadOnlyAccess。详情请参见创建RAM角色并授权。

增加信任策略，允许该RAM角色被可信云服务Hologres扮演。详情请参见修改RAM角色的信任策略。

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "hologres.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}

登录数据湖构建控制台，在目标Catalog中对RAM角色授予DB和表的访问权限。详情请参见授权管理。

在Hologres中创建External Database，认证策略指定上述RAM角色。

CREATE EXTERNAL DATABASE <ext_database_name> WITH
  catalog_type 'paimon'
  metastore_type 'dlf-rest'
  dlf_catalog 'paimon_catalog' 
  rolearn 'acs:ram::106380604****:role/***-ramrole'
  comment 'paimon catalog on dlf'
  ;

在Hologres中创建USER MAPPING，将需要访问DLF Catalog的RAM用户或BASIC账号关联到RAM角色。
```
CREATE USER MAPPING FOR "<RAM用户｜BASIC账号>"
EXTERNAL DATABASE <ext_database_name>
OPTIONS
(
   rolearn 'acs:ram::10638060***:role/***ramrole'
);
```
说明
- 关于USER MAPPING介绍，详情请参见CREATE USER MAPPING。
- 关于创建RAM用户详情，请参见创建RAM用户。
- 关于创建BASIC账号详情，请参见用户管理。
通过RAM用户登录Hologres管理控制台或BASIC账号重新连接Hologres实例后，执行以下查询SQL。
```
SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;
```

湖表镜像加速

Hologres自V3.2版本起，新增湖表镜像功能，以加速湖上数据查询。该功能支持元数据与数据镜像，能够近实时或按指定时间间隔将外部数据源的变更同步至Hologres。此外，还支持全表镜像和分区表的部分镜像，可通过参数灵活控制镜像数据的范围。更多介绍详情，请参见湖表镜像。

External Schema相关操作

创建External Schema至Paimon Catalog

创建EXTERNAL SCHEMA会在DLF Paimon Catalog中实际创建一个Database，代码如下：

-- 创建EXTERNAL SCHEMA
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] <ext_database_name>.<ext_schema_name>;

刷新External Schema元数据

REFRESH CACHE FOR EXTERNAL SCHEMA <ext_database_name>.<ext_schema_name> WITH( cache_level = 'metadata');

删除External Schema

删除EXTERNAL SCHEMA会实际删除Paimon Catalog下对应DB和DB下所有的表，请谨慎操作。

-- 删除EXTERNAL SCHEMA
DROP EXTERNAL SCHEMA [IF NOT EXISTS] <ext_database_name>.<ext_schema_name>;

查看指定Schema下的表

SELECT * FROM hologres.hg_external_tables ('<ext_database_name>', '<ext_schema_name>');

External Table相关操作

创建External Table至Paimon Catalog

-- 创建非分区表

CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name>(
    id TEXT,                                        
    created_at BIGINT,                             
    type TEXT,                                      
    actor_id TEXT,                                  
    actor_login TEXT,                               
    repo_id TEXT,                                   
    repo_name TEXT,                                 
    org TEXT,                                       
    org_login TEXT,                                 
    PRIMARY KEY(id)
) WITH (
  "changelog-producer"='input',
  "bucket"=6,
  "bucket-key"='id'
);

-- 创建分区表

CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name>(
    id TEXT,                                        
    created_at BIGINT,                              
    type TEXT,                                      
    actor_id TEXT,                                  
    actor_login TEXT,                               
    repo_id TEXT,                                  
    repo_name TEXT,                                 
    org TEXT,                                       
    org_login TEXT                                
)
LOGICAL PARTITION BY LIST(created_at)
 WITH (
  "file_format" = 'orc',
  "bucket"=6,
  "bucket-key"='id'
);

刷新External Table元数据

REFRESH CACHE FOR EXTERNAL TABLE <ext_db_name>.<ext_schema_name>.<ext_table_name> WITH( cache_level = 'metadata');

删除External Table

删除External Table会实际删除DLF Paimon Catalog中的表，请谨慎操作。

-- 删除External Table
DROP EXTERNAL TABLE IF EXISTS <ext_database_name>.<ext_schema_name>.<ext_table_name>;

收集外表统计信息

Analyze和Auto Analyze命令用于收集数据库中表内容的统计信息，优化器会根据这些统计信息生成最佳的查询计划，从而提高查询效率，详情请参见ANALYZE和AUTO ANALYZE。

-- 更新某个表的统计信息，默认会收集表中所有列的统计信息
analyze <ext_database_name>.<ext_schema_name>.<ext_table_name>;

-- 更新某个列的统计信息，会比更新表时采样的数据更多，更精准，主要用于更新管理条件的列
analyze <ext_database_name>.<ext_schema_name>.<ext_table_name>(<colname>, <colname>);

-- 打开Auto Analyze
ALTER EXTERNAL DATABASE <ext_database_name> WITH enable_auto_analyze 'true';

TimeTravel查询

Hologres自V3.2版本开始，支持基于Timestamp、Version、Tag对Paimon表进行历史Snapshots查询，从而实现对数据的TimeTravel功能，同时支持在Hologres侧查询Paimon Snapshots、Tags系统表，来获取目标表的Snapshot详情。关于系统表介绍详情，请参见Paimon System Tables。

查询Paimon Snapshots系统表

SELECT * FROM hologres.hg_list_snapshots('<ext_database_name>.<ext_schema_name>.<ext_table_name>;');

Snapshots系统表包含的字段信息与Paimon系统表的对应关系如下：

Snapshots系统表字段	类型	描述	Paimon系统表对应字段
branch_name	TEXT	分支名称。	branch_name
snapshot_id	TEXT	快照ID。	snapshot_id
schema_id	TEXT	表Schema ID。	schema_id
commit_kind	TEXT	表数据提交类型。	commit_kind
commit_time	TIMESTAMPTZ	提交时间。	commit_time
extend_info	TEXT（JSON）	Paimon Snapshots系统表剩余属性。	Paimon Snapshots系统表剩余属性

您也可以通过hologres.hg_list_versions函数来查询Paimon Snapshots系统表，对于Paimon表查询来说，Version对应Snapshots ID。

SELECT * FROM hologres.hg_list_versions('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

查询Paimon Tag系统表

SELECT * FROM hologres.hg_list_tags('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Tag系统表包含的字段信息与Paimon系统表的对应关系如下：

Tag系统表字段	类型	描述	Paimon系统表对应字段
branch_name	TEXT	分支名称。	branch_name
tag_name	TEXT	标签名称。	tag_name
snapshot_id	TEXT	快照ID。	snapshot_id
schema_id	TEXT	表Schema ID。	schema_id
commit_time	TIMESTAMPTZ	提交时间。	commit_time
extend_info	TEXT（JSON）	Paimon Tag系统表剩余属性。	Paimon Tag系统表剩余属性

基于Timestamp查询Paimon历史快照

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR TIMESTAMP AS OF '<timestamp>';

基于Version查询Paimon历史快照

对于Paimon表来说，Version对应Snapshots ID。

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR VERSION AS OF '<version>';

基于Tag查询Paimon历史快照

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR TAG AS OF '<tag>';

Branch查询

Hologres自V3.2.版本开始，支持基于Branch查询Paimon表指定分支数据，并支持分支Fallback属性，更多关于Paimon Branch介绍详情，请参见Manage Branch。

查询Branch系统表

SELECT * FROM hologres.hg_list_branches('<ext_database_name>.<ext_schema_name>.<ext_table_name>');

Branch系统表包含的字段信息与Paimon系统表的对应关系如下：

字段	类型	描述	Paimon系统表对应字段
branch_name	TEXT	分支名称。	branch_name
create_time	TIMESTAMPTZ	分支创建时间。	create_time
extend_info	TEXT（JSON）	Paimon Branch系统表剩余属性。	Paimon Branch系统表剩余属性

查询指定分支数据

SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR branch AS OF '<tag>';

说明

如果Paimon表设置了scan.fallback-branch属性，查询作业从当前分支读取数据时，某个分区不存在，读取器会尝试从备用分支（Fallback Branch）读取该分区的数据。更多关于Fallback Branch介绍详情，请参见Manage Branch。

查询指定分支的历史Snapshots数据

-- 基于Timestamp查询
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR branch AS OF '<branch_name>' TIMESTAMP AS OF '<timestamp>';

-- 基于Tag查询
SELECT * FROM '<ext_database_name>.<ext_schema_name>.<ext_table_name>' FOR branch AS OF '<branch_name>' TAG AS OF '<tag_name>';

使用Foreign Table方式消费Paimon表

创建Foreign Server。

关于Foreign Server的更多操作详情，请参见Foreign Server更多操作（SQL方式）。

-- create foreign server

CREATE SERVER IF NOT EXISTS <server_name> FOREIGN DATA WRAPPER dlf_fdw OPTIONS (
    catalog_type 'paimon',
    metastore_type 'dlf-rest', 
    dlf_catalog '<dlf_catalog_name>'
);

创建外部表。

IMPORT FOREIGN SCHEMA方式

关于IMPORT FOREIGN SCHEMA使用详情，请参见IMPORT FOREIGN SCHEMA。

-- 使用IMPORT FOREIGN SCHEMA创建外表
IMPORT FOREIGN SCHEMA <dlf_db_name>
FROM SERVER <server_name> 
INTO <holo+schema_name> 
options (if_table_exist 'update');

CREATE FOREIGN TABLE方式

关于CREATE FOREIGN TABLE使用详情，请参见CREATE FOREIGN TABLE。

CREATE FOREIGN TABLE <foreign_table_name>
(
  { column_name data_type }
  [, ... ]
) 
SERVER <server_name>
options
(
  schema_name '<dlf_db_name>',
  table_name '<dlf_table_name>'
);

使用Dynamic Table消费Paimon表

Dynamic Table可以自动处理并存储一个或者多个基表（Base Table）对象的数据聚合结果，内置不同的数据刷新策略，业务可以根据需求设置不同的数据刷新策略，实现数据从基表对象到Dynamic Table的自动流转，满足业务统一开发、数据自动流转、处理时效性等诉求。Hologres自V3.0版本开始，支持把MaxCompute外部表和DLF外部表作为Dynamic Table的基表，详见Dynamic Table。

全量刷新

CREATE DYNAMIC TABLE paimon_dt_table
WITH (
      auto_refresh_mode='full',
      freshness='3 minutes'
)AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

增量刷新

CREATE DYNAMIC TABLE paimon_dt_table_increamental
WITH (
      auto_refresh_mode='incremental',
      freshness='3 minutes'
)AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;

自动刷新

CREATE DYNAMIC TABLE paimon_dt_table_auto
WITH (
      auto_refresh_mode='auto',
      freshness='3 minutes'
)AS SELECT * FROM <ext_database_name>.<ext_schema_name>.<ext_table_name>;