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）

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. 数据类型映射（速查）

Tips：时间与时区的处理请在源端/管道层保持一致策略，避免默认时区导致的偏移问题。

7. 性能与成本优化建议

1. 合理分区（partition.key）

   • 订单/日志类表：按 dt（或 dt, hour）分区，兼顾写入与查询的剪裁效率。
   • 维表：通常不分区或轻分区。

2. 表属性（table.properties.*）

   • 将常用的表写入参数集中在这里统一透传，便于跨表一致化治理（如压缩、Compaction、读写并发控制等）。
   • 具体属性名以 Paimon 官方文档为准（建议在灰度环境演练后再上生产）。

3. 并行度（pipeline.parallelism）

   • 起步保守（如 2~4），观察上游压力与下游文件生成速率，再动态扩大。
   • 核心观察指标：Checkpoint 时间、文件数量/大小、Compaction 任务积压等。

8. 常见问题（Troubleshooting）

• 报错：目标表不支持非主键
  说明当前 Sink 仅支持 Paimon 主键表。为表声明主键或在源侧做唯一键重建。

• 表自动创建失败
  检查 catalog.properties.metastore 与 warehouse 路径是否可写；Hive 模式下检查 Metastore 连接与权限。

• Schema 变更未生效/读到空值
  确认变更类型是否兼容；确保先在灰度库验证 Schema 变化，再推广到生产；必要时停任务、做一次兼容迁移。

• 重复数据/版本膨胀
  检查主键是否稳定唯一；确认上游是否产生乱序/回放，必要时在上游做去重或在表属性中开启相应合并策略（以官方表属性为准）。

9. 上线 Checklist（强烈建议）

1. 小表预演：挑 3~5 张小表跑一遍全量+增量，验证自动建表、分区、主键幂等是否符合预期。
2. 字段级对账：抽样进行字段级校验（COUNT(*)、SUM(主键哈希)、关键列分布）。
3. 重启与断点续跑：模拟任务重启，确认不会多写或丢写。
4. 压测与观测：观察 Checkpoint、写入延迟、文件大小与数量，必要时调整 parallelism/分区策略/表属性。
5. 权限与安全：确认仓库路径/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