帮你快速理解、总结文档立即下载
文档中心>流计算 Oceanus>CDC 数据同步开发指南>上下游开发指南>Paimon 连接器

Paimon 连接器

最近更新时间：2026-10-15 11:30:43
我的收藏

本页目录：

Paimon 连接器可以作为 Sink，把上游的变更事件写入 Apache Paimon 湖存储，提供自动建表、表结构变更同步与数据实时同步能力。


前置准备

已部署可用的 Paimon catalog，支持 filesystem 与 hive 两种 metastore。
使用 filesystem metastore 时，作业运行环境需可访问 warehouse 目录，并具备读写权限。
使用 hive metastore 时，需提供 Hive metastore 服务地址，并保证网络可访问。


版本说明

Flink 版本
说明
1.20
基于 Flink-cdc 社区 release-3.6 开发，JDK 版本为 11，支持 Paimon 版本为 0.6、0.7、0.8、0.9、1.0、1.1、1.2、1.3

使用范围

可作为 Sink（type: paimon）使用。


快速示例

从 MySQL 同步到 Paimon：
source:
  type: mysql
  name: MySQL Source
  hostname: 127.0.0.1
  port: 3306
  username: admin
  password: pass
  tables: adb.\\.*
  server-id: 5401-5404

sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: filesystem
  catalog.properties.warehouse: /path/warehouse

pipeline:
  name: MySQL to Paimon Pipeline
  parallelism: 2

使用 Hive metastore 并指定分桶：
sink:
  type: paimon
  name: Paimon Sink
  catalog.properties.metastore: hive
  catalog.properties.uri: thrift://127.0.0.1:9083
  catalog.properties.warehouse: hdfs:///path/warehouse
  table.properties.bucket: 4


Sink 配置项

参数
是否必填
默认值
类型
说明
catalog.properties.metastore
required
(none)
String
Paimon catalog 的类型，可取 filesystem 或 hive。
catalog.properties.warehouse
optional
(none)
String
Paimon 仓库的根目录，无默认值。filesystem 模式下需要配置， 缺少时无法定位存储位置。
例如 /path/warehouse 或 hdfs:///path/warehouse。
catalog.properties.uri
optional
(none)
String
Hive metastore 的服务地址，metastore 为 hive 时需要配置。
例如 thrift://127.0.0.1:9083。
commit.user-prefix
optional
admin
String
提交数据文件时使用的用户名，用于区分不同作业的写入。
也可写作 commit.user。
partition.key
optional
(空)
String
为目标表指定分区字段，详见「分区表」章节。
catalog.properties.*
optional
(none)
String
透传给 Paimon catalog 的参数，属性名去掉该前缀后传给 catalog，
table.properties.*
optional
(none)
String
建表时写入 Paimon 表属性的参数，属性名去掉该前缀后作为表属性，
例如 table.properties.bucket: 4、table.properties.file.format: parquet。
Sink 侧的时区取自 pipeline 配置 local-time-zone，未配置时使用作业运行环境的系统时区。


分区表

通过 partition.key 可以为目标表指定分区字段。多条配置之间用英文分号（;）分隔，
表名与分区字段之间用英文冒号（:）分隔，同一张表的多个分区字段之间用英文逗号（,）分隔。
sink:
  type: paimon
  partition.key: testdb.table1:id1,id2;testdb.table2:name

配置时需要注意：
分区字段会被自动并入主键。即使源表未把这些字段声明为主键，建出的 Paimon 表也会包含它们作为主键的一部分，且这些列会被设为 NOT NULL。源表中该字段存在空值时，请谨慎选择为分区字段。
表名需要与上游表的标识一致，格式为 namespace.tableName。
配置了 partition.key 时，优先使用这里的分区字段；未配置时使用上游表结构自带的分区字段。


表结构变更同步

Paimon Sink 支持下列表结构变更：
变更类型
说明
CREATE TABLE
自动建库建表。
ADD COLUMN
新增列，支持 FIRST、AFTER、BEFORE、LAST 四种位置。
待新增的列已存在时跳过该操作，不导致作业失败。
DROP COLUMN
删除列。待删除的列不存在时跳过该操作，不导致作业失败。
RENAME COLUMN
重命名列。
ALTER COLUMN TYPE
修改列类型，同时更新列注释。
TRUNCATE TABLE
清空表数据。
DROP TABLE
删除表。
ALTER TABLE COMMENT
修改表注释。
需要注意：

上游需要开启表结构变更事件的发送，下游才能感知并同步。以 MySQL 为例，需要开启 Source 侧的 schema-change.enabled。
新增或修改列时，若列的默认值为 0000-00-00 00:00:00，时间戳类型的列会被改写为 1970-01-01 00:00:00，避免写入非法时间值。


自动建表

上游表不存在时，连接器会自动创建对应的 Paimon 表，规则如下：

数据库不存在时自动创建。
列的类型按下表「数据类型映射」转换，并保留列注释。
主键取自上游表的主键；若配置了 partition.key，分区字段会追加到主键中。
表注释取自上游表的注释。
table.properties.* 指定的参数会写入表属性，对所有新建表生效。
上游表没有主键时，创建的是无主键表。无主键表按追加方式写入，只有包含主键的表才能正确处理上游的 UPDATE 与 DELETE 事件，因此建议同步有主键的源表。


数据类型映射

CDC type
Paimon type
NOTE
TINYINT
TINYINT

SMALLINT
SMALLINT

INT
INT

BIGINT
BIGINT

FLOAT
FLOAT

DOUBLE
DOUBLE

DECIMAL(p, s)
DECIMAL(p, s)

BOOLEAN
BOOLEAN

BINARY(n)
BINARY(n)

VARBINARY(n)
VARBINARY(n)

BYTES
BYTES

CHAR(n)
CHAR(n)

VARCHAR(n)
VARCHAR(n)

STRING
STRING

DATE
DATE

TIME(p)
TIME(p)
未显式指定精度时为 0。
TIMESTAMP(p)
TIMESTAMP(p)
未显式指定精度时为 6。
TIMESTAMP_LTZ(p)
TIMESTAMP WITH LOCAL TIME ZONE(p)
未显式指定精度时为 6。
VARIANT
VARIANT

中国站