基于DLF访问Paimon Catalog_实时数仓 Hologres(Hologres)-阿里云帮助中心

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

背景信息

阿里云数据湖构建（Data Lake Formation，简称DLF）是一款全托管的统一元数据和数据存储及管理平台，为客户提供元数据管理、权限管理和存储优化等功能。该平台能够实现元数据的统一、湖表格式的统一以及数据存储的统一，显著简化客户在数据湖构建和管理过程中的运维工作，助力企业聚焦于业务创新和数据洞察。详情请参见什么是数据湖构建。

功能详情

Hologres自3.2版本开始支持以下功能：
- 通过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。
Hologres自4.0版本开始支持丰富的DML操作：
- 多并发写入Paimon主键表，支持INSERT INTO和INSERT OVERWRITE两种写入方式，并优化了写入流程，支持按Bucket进行shuffle后再写入，以减少小文件产生。
- 提供基于内存的缓存机制来支持写入需要缓存机制的Paimon表，如Merge Engine为Fisrt Row、通过lookup机制生成Changelog或者开启了Deletion Vector的表。
- 支持对Paimon表进行UPDATE、DELETE操作。

前提条件

已开通2.5及以上版本的DLF服务并新建Paimon Catalog。详情请参见授权并开通DLF和数据目录。
说明
支持的地域详见服务接入点。
已购买Hologres实例并开通数据湖加速服务。详情请参见环境配置。

使用限制

仅支持访问同地域的DLF服务。
暂不支持使用HoloWeb中的OSS数据湖加速功能可视化创建DLF Paimon Catalog。
仅External Database方式映射的Paimon外表支持TimeTravel查询、Branch查询和数据镜像能力。
暂不支持对发生Schema Evolution的表执行TimeTravel查询。
Dynamic Table暂不支持Paimon表和Branch的TimeTravel查询。
外部表镜像暂不支持Paimon主键表。
不支持读取Paimon默认分区数据，如分区值为空或者NULL的分区。
只读从实例暂不支持开启数据湖加速能力。
不支持对外部表执行TRUNCATE命令，可使用INSERT OVERWRITE插入空数据代替。
不支持写入Paimon的动态分桶表，即创建Paimon表时未指定bucket参数或指定了bucket = -1。
仅支持对Merge Engine为deduplicate或partial-update的Paimon主键表执行UPDATE操作，且不支持更新主键。
仅支持对Merge Engine为deduplicate或partial-update（需打开partial-update.remove-record-on-delete属性）的Paimon主键表执行DELETE操作。
外表不支持DML混合事务，仅在单次DML过程中实现了两阶段提交，保证分布式写入过程的原子性。

使用External Database方式映射Paimon Catalog

创建External Database（SLR模式）

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

适用场景

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

操作步骤

对于新购或升级至Hologres V2.2及以上版本的实例，系统会默认创建服务关联角色，无需手动创建，可跳过该步骤。
说明
Hologres V2.2以下版本的实例，需访问控制快速授权页面，创建服务关联角色。

连接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>;

创建External Database（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>;
```

External Database相关操作

查看实例中的External Database

SELECT database_name, options FROM hologres.hg_external_databases();

刷新External Database元数据

REFRESH CACHE FOR EXTERNAL DATABASE <EXT_DB_NAME> WITH( cache_level = 'metadata');

查看指定External Database下的Schema

SELECT * FROM hologres.hg_external_schemas('<ext_database_name>');

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>';

湖表镜像加速

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

使用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>;

DML操作

INSERT INTO

-- 使用Hologres SQL创建Paimon主键表并插入数据

CREATE EXTERNAL TABLE  <ext_database_name>.<ext_schema_name>.<ext_table_name> (
id BIGINT,
customer_id BIGINT,
item TEXT,
amount FLOAT,
dt TEXT,
PRIMARY KEY (id)
)
WITH (
"table_format" = 'paimon',
"file_format" = 'orc',
"merge-engine" = 'deduplicate', -- 合并策略示例，可按需修改
"bucket" = '4' -- 示例 bucket 数
);

INSERT INTO <ext_database_name>.<ext_schema_name>.<ext_table_name> (id, customer_id, item, amount, dt) VALUES
(1, 1001, 'apple', 3.50, '2025-09-10'),
(2, 1002, 'banana', 2.00, '2025-09-10'),
(3, 1003, 'orange', 4.20, '2025-09-11');

INSERT OVERWRITE

-- 使用Hologres SQL创建Paimon Append Table并插入数据

CREATE EXTERNAL TABLE <ext_database_name>.<ext_schema_name>.<ext_table_name> (
id BIGINT,
name TEXT,
amount FLOAT8,
dt TEXT
)
LOGICAL PARTITION BY LIST(dt)
WITH (
"table_format" = 'paimon',
"file_format" = 'parquet',
"merge-engine" = 'deduplicate', 
"bucket-key" = 'id',
"bucket" = '2'
);

INSERT OVERWRITE <ext_database_name>.<ext_schema_name>.<ext_table_name>(id, name, amount, dt) VALUES
(1, 'Alice', 100.50, '2025-09-01'),
(2, 'Bob', 200.00, '2025-09-01'),
(3, 'Carol', 150.75, '2025-09-02');

UPDATE

UPDATE <ext_database_name>.<ext_schema_name>.<ext_table_name> SET amount= 5 where id= 1;

DELETE

DELETE FROM <ext_database_name>.<ext_schema_name>.<ext_table_name> WHERE id = 2;