1. 为什么在 Pipeline 里选择 Paimon？
- 自动建表 & Schema 同步：首次运行时可自动建表，后续字段新增等变更可自动跟随（受具体变更类型约束，建议先灰度验证）。
- 主键表 + 幂等写：结合主键做 upsert，天然适配增量 CDC 的幂等语义（重复到达不造成多版本垃圾）。
- 数据湖形态：批流统一表存储，后续离线或流式分析可直接复用同一份 Paimon 表。
注意：仅支持 主键表。源表必须有主键；没有主键的宽表请先补充主键或做唯一键重建。
2. 五分钟起步：从 MySQL 同步到 Paimon
下面是一份最小可用的 Pipeline 配置（含 MySQL 源与 Paimon 目标），可直接作为模板：
source:
type: mysql
name: MySQL Source
hostname: 127.0.0.1
port: 3306
username: admin
password: pass
tables: adb.\.*, bdb.user_table_[0-9]+, [app|web].order_\.*
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易错点提示
tables支持正则；.被视作库/模式/表分隔符，若要匹配任意字符请写\.。- Paimon Sink 需要可写的
warehouse路径（filesystem模式）；若采用 Hive Metastore，请配置catalog.properties.metastore: hive与对应catalog.properties.uri。
3. 关键配置项一览（Sink）
| 选项 | 必填 | 默认 | 类型 | 说明 |
|---|---|---|---|---|
type | ✅ | — | String | 固定为 paimon |
name | — | String | Sink 名称（便于识别） | |
catalog.properties.metastore | ✅ | — | String | Catalog 元数据存储：filesystem 或 hive |
catalog.properties.warehouse | — | String | 仓库根路径（filesystem 必配；hive 也建议配置） | |
catalog.properties.uri | — | String | 元数据服务 URI（如 Hive Metastore Thrift URI） | |
commit.user | "admin" | String | 写入提交用户标识 | |
partition.key | — | String | 多表分区键配置：表与键用 ; 分隔，键之间用 , 分隔。例：testdb.table1:id1,id2;testdb.table2:name | |
catalog.properties.* | — | String | 透传给 Paimon Catalog 的参数 | |
table.properties.* | — | String | 透传给 Paimon 表的参数（如分桶/合并策略/压缩等，具体以 Paimon 文档为准） |
Hive Metastore 示例
sink:
type: paimon
name: Paimon Sink (Hive)
catalog.properties.metastore: hive
catalog.properties.uri: thrift://hms-1:9083
catalog.properties.warehouse: hdfs:///warehouse/paimon多表分区示例
sink:
type: paimon
name: Paimon Sink
catalog.properties.metastore: filesystem
catalog.properties.warehouse: /data/warehouse
partition.key: adb.orders:dt; adb.users:region,dt含义：
adb.orders以dt分区；adb.users以region, dt复合分区。
4. 一致性语义与幂等策略
- 一致性语义：at-least-once。
- 如何确保结果正确？ 依赖 Paimon 主键表 的 Upsert 语义（幂等），相同主键的重复事件最终只保留期望版本。
- 生产建议：源端必须定义主键；如源端是 MySQL CDC，则天然具备主键/唯一约束，落到 Paimon 可 1:1 映射为主键表。
5. 自动建表与 Schema 变更
- 自动建表：目标表不存在时自动创建；表结构来自源端表结构与数据类型映射。
- Schema 变更同步：新增字段等向前兼容变更一般可同步。对破坏性变更（删列、类型下调、重命名）建议走变更流程并灰度验证。
- 最佳实践：将 DDL 纳入 CI/CD（Liquibase/Flyway 等），通过“变更申请 → 灰度验证 → 正式发布”的方式，降低不兼容风险。
6. 数据类型映射（速查）
| CDC type | Paimon type | 说明 |
|---|---|---|
| TINYINT | TINYINT | |
| SMALLINT | SMALLINT | |
| INT | INT | |
| BIGINT | BIGINT | |
| FLOAT | FLOAT | |
| DOUBLE | DOUBLE | |
| DECIMAL(p, s) | DECIMAL(p, s) | |
| BOOLEAN | BOOLEAN | |
| DATE | DATE | |
| TIMESTAMP | TIMESTAMP | |
| TIMESTAMP_LTZ | TIMESTAMP_LTZ | |
| CHAR(n) | CHAR(n) | |
| VARCHAR(n) | VARCHAR(n) |
Tips：时间与时区的处理请在源端/管道层保持一致策略，避免默认时区导致的偏移问题。
7. 性能与成本优化建议
合理分区（partition.key）
- 订单/日志类表：按
dt（或dt, hour）分区，兼顾写入与查询的剪裁效率。 - 维表：通常不分区或轻分区。
- 订单/日志类表：按
表属性（table.properties.*）
- 将常用的表写入参数集中在这里统一透传，便于跨表一致化治理（如压缩、Compaction、读写并发控制等）。
- 具体属性名以 Paimon 官方文档为准（建议在灰度环境演练后再上生产）。
并行度（pipeline.parallelism）
- 起步保守（如 2~4），观察上游压力与下游文件生成速率，再动态扩大。
- 核心观察指标：Checkpoint 时间、文件数量/大小、Compaction 任务积压等。
8. 常见问题（Troubleshooting）
报错：目标表不支持非主键
说明当前 Sink 仅支持 Paimon 主键表。为表声明主键或在源侧做唯一键重建。表自动创建失败
检查catalog.properties.metastore与warehouse路径是否可写；Hive 模式下检查 Metastore 连接与权限。Schema 变更未生效/读到空值
确认变更类型是否兼容；确保先在灰度库验证 Schema 变化，再推广到生产；必要时停任务、做一次兼容迁移。重复数据/版本膨胀
检查主键是否稳定唯一；确认上游是否产生乱序/回放，必要时在上游做去重或在表属性中开启相应合并策略（以官方表属性为准）。
9. 上线 Checklist（强烈建议）
- 小表预演：挑 3~5 张小表跑一遍全量+增量，验证自动建表、分区、主键幂等是否符合预期。
- 字段级对账：抽样进行字段级校验（
COUNT(*)、SUM(主键哈希)、关键列分布）。 - 重启与断点续跑：模拟任务重启，确认不会多写或丢写。
- 压测与观测：观察 Checkpoint、写入延迟、文件大小与数量，必要时调整 parallelism/分区策略/表属性。
- 权限与安全：确认仓库路径/HMS 权限、网络 ACL、账号仅授予必要权限。
10. 进阶示例：多表分区 + 透传表属性
下例演示按表名分别配置分区键，并透传一些（示例）表属性供统一管理（具体属性名与含义以 Paimon 文档为准）。
sink:
type: paimon
name: Paimon Sink (Advanced)
catalog.properties.metastore: filesystem
catalog.properties.warehouse: /data/warehouse
# 多表分区键
partition.key: sales.orders:dt; dim.users:region,dt
# 统一透传 Catalog/Table 属性（示例名，按需调整）
catalog.properties.owner: data-platform
table.properties.file.compress: true
table.properties.compaction.enabled: true