在实际生产中，合理规划 Apache Paimon 主键表（Primary Key Table）的 Bucket（分桶）数量，对表的读写性能、小文件控制以及计算资源消耗有着至关重要的影响。根据 Paimon 最新 master 分支文档的设计，Bucket 是读写的最小存储和并发单元，每个 Bucket 目录在底层对应一棵独立的 LSM 树。

以下结合 Paimon 官方文档的核心概念、分桶模式、计算公式以及运维机制，详细梳理在生产中规划 Bucket 的方法和最佳实践。

一、 核心规划原则：单桶大小与并发

在规划 Bucket 数量时，首先要明确两条核心约束线：

1. 单个 Bucket 的推荐数据大小：200 MB - 1 GB
   • Bucket 过多：由于每个 Bucket 自成一棵 LSM 树，分桶过多会导致并发写入时产生大量细碎的小文件，从而加重集群元数据管理负担，并显著降低读取性能。
   • Bucket 过少：如果单桶承载的数据量过大（例如超过数 GB 甚至数十 GB），会导致单桶内的 LSM 树过于庞大，引发严重的合并（Compaction）瓶颈与写入延迟。
2. 读写最大并行度（Parallelism）受限于 Bucket 数量
   • 每一个 Bucket 在同一时间通常只能由一个 Flink Subtask 写入。这意味着在固定分桶模式下，Bucket 数量决定了该表写入和读取的最大吞吐并发度。

二、 两种分桶模式的规划选择

Paimon 主键表支持 动态分桶（Dynamic Bucket） 和 固定分桶（Fixed Bucket）。生产规划的第一步是根据业务场景确定使用哪种模式。

1. 动态分桶模式（Dynamic Bucket）

• 配置方式：不配置 bucket 或设置 'bucket' = '-1'（主键表默认即为此模式）。
• 工作原理：Paimon 会在后台自动维护一个索引文件（Index），记录主键 Hash 值与 Bucket 的映射关系。随着数据行数增长，Paimon 会自动扩容分桶数量。
• 适用场景：
  • 数据体量难以准确预估的表，或包含大量不活跃历史分区的 partitioned 表。
  • 表更新率较低，想省去人工运维成本的场景。
• 生产参数规划：
  • dynamic-bucket.target-row-num（默认 200 万行）：用于控制单个 Bucket 推荐承载的最大行数。在生产中，若单行较宽，建议将该值调小；若单行很窄，可适当调大，目标是让物理大小落在 200MB - 1GB 范围内。
  • dynamic-bucket.initial-buckets：初始分桶数。如果表初始化时就有海量历史数据写入，建议调大此值，避免频繁自动扩容带来的开销。
  • dynamic-bucket.max-buckets：最大分桶上限限制，防止数据倾斜或异常行数导致分桶无限制增加。
• 生产注意事项（避坑）：
  • 不能多任务并发写入：动态分桶仅支持单一作业（Single Write Job）写入。严禁启动多个作业同时往同一个分区写数据，否则由于索引状态不共享，会产生数据重复（Duplicate Data）。
  • 内存开销：由于需要将 Mapping 索引保存在内存中，通常在普通动态分桶模式下，分区内每 1 亿条主键记录会额外消耗约 1 GB 内存（好在不活跃的分区索引不会常驻内存）。
  • 跨分区更新开销：若主键未包含所有分区字段，需要启用跨分区更新。此时本地磁盘会维护 RocksDB 索引，大表在流作业启动时初始化加载时间较长，需要调优配置 cross-partition-upsert.index-ttl 控制索引生命周期。

2. 固定分桶模式（Fixed Bucket）

• 配置方式：配置 'bucket' = '<num>'（其中 <num> 为大于 0 的整数）。
• 工作原理：根据主键（或指定的 bucket-key）的哈希值做模运算计算落入的分桶（Math.abs(key_hashcode % numBuckets)）。
• 适用场景：
  • 超高吞吐写入、需要多作业并发写入同一张表或同一个分区的场景。
  • 资源有限、希望避免动态分桶维护内存索引开销的场景。
• 固定分桶数的计算公式：
  $$\text{单分区 Bucket 数量} = \frac{\text{单分区/单表预计存储总数据量}}{\text{500 MB (或 200 MB - 1 GB 中的推荐值)}}$$
  • 例如：某主键表采用天分区（dt），预估每天新增的物理数据量约为 20 GB。若按照每个 Bucket 容纳 500 MB 数据计算，则可将 Bucket 数规划为：$20 \text{ GB} / 500 \text{ MB} = 40$。
• 与计算引擎并行度的关系：
  • 在 Flink 流式写入中，如果 Bucket 数多于 Flink Sink 算子的并行度，可能会导致部分 Bucket 在一个 checkpoint 周期内没有数据写入。
  • 反之，如果并行度远大于 Bucket 数，会导致多个 Subtask 竞争向同一个 Bucket 写入（即产生多写入源），影响合并性能。
  • 推荐比例：一般建议 Bucket 数量与 Flink Sink 写入并行度保持 1:1 或 2:1 的比例，或者让 Bucket 数量是并行度的整数倍，以保证负载相对均衡。

三、 合理规划 bucket-key

在主键表中，默认会使用 全部主键 作为 bucket-key 决定数据的分桶分布。但在某些特定的生产查询场景下，显式指定 bucket-key 能够带来显著的性能收益：

1. 利用 Data Skipping 减少 I/O 扫描：
   如果您的业务查询条件中，经常会对某些非完整主键的特定字段进行等值查询（=）或 IN 过滤，可以将其指定为 bucket-key。这样 Paimon 在查询时可以直接定位并只读取命中的分桶，跳过其余分桶的文件。
2. 加速 Bucketed Join（免 Shuffle Join）：
   在 Batch（批处理）场景下，如果有两张大表需要经常进行 Join。如果两张表都以相同的字段作为 bucket-key，并且规划了完全相同的 Bucket 数量，那么引擎（如 Spark）在 Join 时可以实现 Bucketed Join。这能完全避免昂贵的数据 Shuffle 过程，极大加速计算。

四、 生产后期的分桶调整（Rescale）

在实际生产中，由于业务增长，原本规划的固定 Bucket 数量可能会不满足当下的体量（单桶变得过大）。Paimon 提供了 Rescale Bucket（重缩放）机制，允许在不重建表的情况下调整分桶数：

1. 修改元数据：
   通过 SQL 命令行调整表的 Bucket 数量：
   sql

   ALTER TABLE table_identifier SET ('bucket' = '<new_bucket_num>');

2. 重整历史数据（INSERT OVERWRITE）：
   修改元数据并不会自动改变已有文件的数据分布。因此，需要执行一次离线的重写任务：
   sql

   INSERT OVERWRITE table_identifier SELECT * FROM table_identifier;

   在执行该 Overwrite 作业时，Paimon 框架会自动读取旧分桶的数据，并根据新的 Bucket 数量进行重新 Hash 和物化分布。此方法也支持针对特定分区（Partition）进行局部 Rescale，以降低重写开销。