第5章 Spark4.x 分区、分桶、排序与数据裁剪

第5章 Spark4.x 分区、分桶、排序与数据裁剪

章节定位：第 4 章教你读计划，本章教你让计划有东西可裁。优化器再聪明，也只能在物理布局给出的可能性里挑。分区、分桶、排序这三件事是建表时一次定死、事后改起来最贵的三个决定，所以必须放在湖仓读写（第 8-11 章）之前讲透。

本章同时是全系列与前作的一次正式对齐：ck 第 4 章那张"分区 → 主键 → 跳数索引 → 预计算"的裁剪漏斗，在 Spark + 列式文件上的对应形态是"分区 → 文件 → row-group → 行"。四层顺序不变，每层的名字和观测指标不同，判据完全一致：先问这一层裁掉了多少，再问下一层值不值得做。

学习目标

• ✓ 分得清三种"分区"（Hive 目录分区 / Iceberg 隐藏分区 / Paimon 分区 + Bucket），能各自说出：裁剪由谁负责、谓词怎么写才命中、粒度变细的代价落在哪里
• ✓ 拿到一条慢 SQL，能按六种典型失效写法逐条排查分区裁剪，并写出修复版；能区分"没裁"与"裁了但没用"
• ✓ 说清列式文件的四层统计粒度（文件列统计、row-group 的 min/max、page 级索引）分别被谁使用，并知道 Spark 官方只给了前两层的开关，第三层没有官方依据
• ✓ 能判断一张表该怎么排：线性排序、表级 WRITE ORDERED BY、还是多维 Z-Order / Hilbert，依据是查询形态而不是"听说 Z-Order 快"
• ✓ 讲清 Paimon bucket / Iceberg bucket(n) / Hive bucket 的语义差异，以及"分桶表 join 免 shuffle"成立的前提条件
• ✓ 在同一张表的四种布局状态下量出扫描文件数与行数的差，并且知道为什么在 20 万行的数据上量不出来
• ✓ 面对一个新需求，能用"分区定目录、分桶定文件、排序定块"三句话写出 DDL 草案，并说明每个选择的依据

5.1 三种"分区"，为什么会互相混淆

先给结论，后面都在解释这句话：

**它们不是"同一件事的三种实现"，而是三种不同的物理承诺。**承诺不同，所以谓词的写法、失效的样子、变细的代价，全都不一样。

车联网这条链路上三种表格式常年共存：Flink 写的 Paimon ODS、Spark 写的 Iceberg DWD/DWS、存量数仓留下的 Hive 分区表。同一条"按天查一台车"的 SQL 打到三种表上，可能是三种结果——快、慢、或者静悄悄地返回空。第三种最危险，后面 5.2 案例 5 专门讲它。

5.1.1 一张对照表把差异钉住

表 5-1 三种分区机制对照

三个"所以"值得单独记：

① 所以 Iceberg 表里查不到分区列。 第 2 章建的 iceberg.demo.dws_vehicle_daily 用 PARTITIONED BY (months(report_date))，你 SELECT 里写不出 report_date_month——那是隐藏分区字段，在元数据里，不在 schema 里。想验证分区怎么切的，得去读元数据表（Spark 侧用点号访问 iceberg.demo.dws_vehicle_daily.partitions；前作硬约束：Flink 侧写 $partitions，两者不可混用）。

② 所以 Paimon 的桶不是"性能旋钮"，是"定位规则"。 第 2 章那张 ODS 表 'bucket' = '4'、主键 vin,report_date,__dt__。查询里给 vin 等值 ⇒ 能定到一个桶；给 speed > 60 ⇒ 与桶无关，四个桶全开。这不是实现缺陷，是 hash 分桶的数学性质：hash 只支持等值。

③ 所以"Hive 分区数别太多"这条老经验，在湖表上换了形式但没消失。 前作在 Iceberg 系列里定下的口径是：隐藏分区遵循**“几千量级分区”**原则，分区粒度过细导致元数据膨胀。目录分区膨胀的是 metastore 与 list 调用，隐藏分区膨胀的是 manifest；两者都是"元数据先扛不住，查询才慢"。按天分区跑三五年是几千量级，安全；按小时且多维（天 × 城市 × 车型）很容易直接上万，那就要重新想。

5.1.2 三者各管一段物理布局

一张表的物理布局，三件事作用在三个层次
┌──────────────────────────────────────────────────────────────────┐
│ │
│ 分区 Partition → 决定数据落到"哪个目录 / 哪套 spec" │
│ 粒度：天、月、城市段 命中一条 ⇒ 整个目录根本不被打开 │
│ │ │
│ ├── 分桶 Bucket → 决定分区内的"文件归属规则" │
│ │ hash(key) % N 命中 ⇒ 只打开约 1/N 的文件 │
│ │ │ 同时给 join 提供"免 shuffle"的性质 │
│ │ │ │
│ │ └── 文件 File → 列式存储的最小管理单位 │
│ │ │ │
│ │ └─ 排序 Sort / Z-Order │
│ │ 决定"一个文件内部行的先后顺序" │
│ │ 命中 ⇒ 同一文件内跳过 row-group / page │
│ │ │
└──────┴───────────────────────────────────────────────────────────┘

裁剪粒度由外到内： 目录 >> 文件 >> 块（row-group） >> 行
每往里一层，单位小一到两个数量级，但能裁的条件类型也变少。

图 5-1 分区 × 分桶 × 排序在物理布局上的作用位置

这张图后面反复用。三条读法：

• 外层裁掉的是"根本不打开"，内层裁掉的是"打开了但跳过块"。 前者省的是 list + 元数据 + IO 的全部，后者省的是 IO 的一部分。所以顺序永远是：先把分区设计对，再谈排序。
• 三层不互相替代。 有人想用 Z-Order 补分区没分好的洞——它能补一点（多维相关性），但补不了"这个文件里 90% 的行都不该被读"这种结构性浪费。反过来，分区切得再细，文件内部乱序，row-group 的 min/max 就宽到没有任何裁剪价值。
• 分桶是唯一同时影响读和写的层。 它既裁文件，又决定 join/aggregate 需不需要 shuffle。所以它的选择空间最小：桶键必须是高频等值列，桶数一旦定下就很难改。

与 ck 第 4 章的对应关系：ClickHouse 的"分区键 → 排序键 granule → 跳数索引 → 投影"，在 Spark 湖表上就是"分区 → 文件/row-group min-max → page index/bloom → 聚簇排序"。差别在于 ClickHouse 的排序键是写死在 part 内部的强约束（granule 边界靠 mark 文件精确可查），而湖表的"排序"是一次性的写入布局，写完就不再维护顺序——它靠的是统计信息，不是 mark 索引。这个差别在 5.4.4 会量化。

5.2 分区裁剪：六种失效写法

先解决"怎么知道裁没裁"，再讲六种失效。第 4 章 4.2.5 埋的那个负面结果——两条查询读了同样多的文件——就是从这里开始查的。

5.2.1 三个观测点，按可信度排序

三个必须一起用。只看 PartitionFilters 会被案例 5 骗；只跑一次看 UI 又太贵。生产上的标准动作是：先 SHOW PARTITIONS 确认分区值形态，再 EXPLAIN 确认表达式形态，最后用 measure_scan.py（5.6）量一次真实文件数。

— 观测点 3 的固定动作：先看清分区值到底长什么样
SHOW PARTITIONS paimon.demo.ods_vehicle_telemetry;
— 输出列：partition(STRING)，形如 __dt__=2026-10-15，共 30 行
— 验收：30 行；值全部为 yyyy-MM-dd 形式；min=2026-10-01，max=2026-10-30

参数说明：SHOW PARTITIONS 对 Paimon/Hive 风格的显式分区列直接列目录；Iceberg 的隐藏分区不显示在这里，要查元数据表。

输出表结构：单列 partition(STRING)。

验收标准：行数等于第 2 章记录的 30 个分区；任何一行的值形态与后面 SQL 里写的字面量不一致，就先别往下做——这是案例 5 的入口。

5.2.2 表 5-2 六种失效速查

表 5-2 分区裁剪失效速查（每一行后面都有可跑的实验）

第 4 行是这张表里唯一"反常识"的：它不是失效，是收益归零。 很多人看到 PartitionFilters 非空就以为优化生效了，实际读了 29/30 个分区。这一行的价值在于告诉你："裁剪生效"这个结论必须由 files read 给出，不能由 EXPLAIN 给出——这就是第 4 章 4.2 那条"Spark 的计划里只有估算，没有实测"的具体后果。

5.2.3 六个案例逐个跑

以下全部基于第 2 章的 paimon.demo.ods_vehicle_telemetry（20 万行、30 个分区）。每个案例给「反例 → 修复 → 判据」。建议把六段一起存成 pruning_fail_cases.sql，作为团队的谓词评审用例集。

案例 1：函数包裹分区列

— 反例 1A：对分区列套函数
EXPLAIN FORMATTED
SELECT vin, avg(speed) FROM paimon.demo.ods_vehicle_telemetry
WHERE to_date(__dt__) = DATE '2026-10-15'
GROUP BY vin;

— 反例 1B：对时间列套函数（这张表里 report_date 不是分区列，__dt__ 才是）
WHERE date_format(reported_at, 'yyyy-MM-dd') = '2026-10-15'

— 修复 1A：把函数从列侧挪走，直接比较分区列
WHERE __dt__ = '2026-10-15'

— 修复 1B：走真正存在的分区列，时间函数只用于选区间
WHERE __dt__ BETWEEN '2026-10-15' AND '2026-10-15'
AND reported_at >= TIMESTAMP '2026-10-15 00:00:00'
AND reported_at < TIMESTAMP '2026-10-16 00:00:00'

参数说明：1A 的失效原因最直白——裁剪是拿分区值（字符串 2026-10-15）去和谓词比较，套上 to_date() 后优化器需要"知道"函数在分区值域上的映射，Spark 不做这种反演（除少数官方列出的可下推表达式外）。1B 是生产里更高频的版本：reported_at 不是分区列，__dt__ 才是，过滤写错列 = 一定全表扫，无论有没有函数。

修复版 1B 的写法有个刻意的设计：用 >= / < 而不是 BETWEEN 包住时刻列，避免边界日的重复计数；__dt__ 的区间条件与它等价，保留是为了让"分区先裁到 1 个"这个意图在 SQL 里显式可见。

输出表结构：vin(STRING), avg(speed)(FLOAT)。

验收标准：反例的 FileScan 节点 PartitionFilters: 这一行为空 []，UI files read 覆盖 30 个分区；修复版 PartitionFilters 含 isnotnull(__dt__) 与等值/区间条件，files read 约为反例的 1/30。如果反例在你的版本里 PartitionFilters 非空，说明该版本已能对 to_date(字符串) 做常量折叠（__dt__ 是常量时可折），把这条例外记进 5.2.6 的差异表，别改判据。

案例 2：类型与字面量不匹配

— 反例：__dt__ 是 STRING，给了一个整数
EXPLAIN FORMATTED
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ = 20261015; — 注意：没有引号

— 修复：按分区列的真实类型写
WHERE __dt__ = '2026-10-15';

— 对照组：同一张 Iceberg 表（分区列是 DATE），写法又不同
SELECT count(*) FROM iceberg.demo.dws_vehicle_daily
WHERE report_date = DATE '2026-10-15'; — DATE 列配 DATE 字面量

参数说明：这一组的重点不是"会不会报错"，而是同一语义在三种表里写法不同：Hive 风格的 __dt__ STRING 用字符串，Iceberg 的 months(report_date) 用原始 DATE 列，Paimon 的 __dt__ 也是字符串且同时是主键的一部分。跨引擎链路里最常见的事故就是"Flink 侧按 yyyyMMdd 写、Spark 侧按 yyyy-MM-dd 读"——它就是案例 5。

ANSI 相关提醒：Spark 4.0 起 spark.sql.ansi.enabled 默认 true（第 2 章已取证），字符串向数值/日期的隐式转换在 ANSI 下更容易直接抛错而不是静默给 NULL。这是好事——但别把它当保险，第 5 种失效（格式不一致）在 ANSI 下依然静默返回空。

输出表结构：count(BIGINT)。

验收标准：反例的返回值要么是 0（当成不命中）、要么整段抛类型错。两种都可接受，但必须能解释是哪一种；修复版应返回该分区行数（约 6666 行，20 万 ÷ 30，主键去重后按实际记录）。

案例 3：OR 把分区谓词降级

— 反例
EXPLAIN FORMATTED
SELECT vin, speed FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ = '2026-10-15' OR city_id = 310007;

— 修复 A：拆 UNION ALL，每支自己可裁
SELECT vin, speed FROM ... WHERE __dt__ = '2026-10-15'
UNION ALL
SELECT vin, speed FROM ... WHERE city_id = 310007 AND __dt__ <> '2026-10-15';

— 修复 B：如果业务真实意图是"且"，那就是写错了，改成 AND
WHERE __dt__ = '2026-10-15' AND city_id = 310007;

参数说明：析取式要求每一支都能给出分区边界，否则整体没有上界。修复 A 里第二支带了 __dt__ <> '2026-10-15'，是为了防止两支重叠返回重复行（UNION ALL 不去重）——这个写法把代价说得很清楚：OR 的另一支如果要按非分区列查，它无论如何是全分区扫，拆不拆都一样。所以真正的决策是修复 B：先确认业务是不是要 AND。生产上 90% 的这类 OR 是笔误。

输出表结构：vin(STRING), speed(FLOAT)。

验收标准：反例 PartitionFilters 为空且 files read ≈ 全表；修复 B 的 files read ≈ 1/30。修复 A 只应在结果确实要"并集"时用——它把一次全表扫换成了"一次 1/30 扫 + 一次全表扫"，比反例更慢，唯一收益是第一支的结果能早出来。这一条写在这里是为了让读者明白："拆 OR"不是通用药，先问语义。

案例 4：否定谓词——能裁，但裁不动

— "排除一天"
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry WHERE __dt__ <> '2026-10-15';

— "最近 7 天之外"
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry WHERE __dt__ > '2026-10-23';

— 正向枚举修复
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ IN ('2026-10-24','2026-10-25','2026-10-26','2026-10-27',
'2026-10-28','2026-10-29','2026-10-30');

参数说明：<> 在字符串分区上能裁（排除被点名的分区值），所以 PartitionFilters 非空——但只省 1/30。反过来，> / BETWEEN / IN (枚举) 这些能给出有限集合或连续区间的谓词才是裁剪喜欢的形状。修复版和 > 版结果相同，区别在于枚举让"读 7 个分区"这件事在 SQL 里可见，而 > 依赖优化器把区间翻译成分区集合——两种都能裁，但枚举写法在跨引擎（走 metastore 列分区）时更稳。

输出表结构：count(BIGINT)。

验收标准：三个查询各自 PartitionFilters 都非空；对比 files read：<> 版 ≈ 29 个分区，> 版与 IN 版 ≈ 7 个分区。如果 <> 版读到的是全部分区而不是 29 个，说明该源的分区列表获取本身没有被谓词过滤（常见于 metastore 缓存或某些 catalog 实现），把这条记进 5.2.6。

案例 5：分区值格式不一致（本表最危险的一例）

— 目录里是 2026-10-15，条件写成紧凑格式
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry WHERE __dt__ = '20261015';
— ↑ 返回 0 行，不报错，执行得还很快

— 防御性对账：先看分区值形态，再写查询
SHOW PARTITIONS paimon.demo.ods_vehicle_telemetry;

— 上线断言（Spark SQL 里做下限校验，让"0 行"变成一次失败）
SELECT if(count(*) = 0,
raise_error('分区 2026-10-15 无数据：检查 __dt__ 格式与写入侧是否一致'),
count(*)) AS rows_checked
FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ = '2026-10-15';

参数说明：这一例和前四例性质不同——前四例的症状是"慢"，这一例的症状是**“对不上账”**。裁剪机制完全正常，它精确地命中了 0 个分区。车联网链路里它的发生条件很具体：Flink 侧作业用 yyyyMMdd 写 __DT__，Spark 批侧按 yyyy-MM-dd 读；或同一条链路上游换了一次时间格式化模式。第 2 章造数时刻意让 __dt__ 与 report_date 同源、并统一用 date_format(…, 'yyyy-MM-dd')，就是为了把这类问题在实验环境里排除掉，让六个案例的其它变量干净。

raise_error 是 Spark 内置函数，用一行 SQL 把"空结果"升级为作业失败，比事后看板发现数字为 0 便宜得多。生产上这类断言应该出现在每个批作业的开头，而不是最后。

输出表结构：rows_checked(BIGINT)。

验收标准：紧凑格式那条返回 0；断言版在正常分区上返回约 6666，把日期改成一个不存在的分区值时应抛错并终止作业。抛错这条必须真跑一次——没见过它失败的团队，等于没有这道保险。

案例 6：分区列进了 SELECT 再过滤

— 反例：在 CTE 里造派生列，外层过滤派生列
WITH t AS (
SELECT vin, speed, substr(__dt__, 1, 7) AS month_str
FROM paimon.demo.ods_vehicle_telemetry
)
SELECT count(*) FROM t WHERE month_str = '2026-10';

— 修复 A：谓词写回原始分区列，用区间
SELECT count(*) FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ >= '2026-10-01' AND __dt__ <= '2026-10-31';

— 修复 B：CTE 内层就过滤（视图/公共 CTE 被复用时唯一可行的做法）
WITH t AS (
SELECT vin, speed FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ >= '2026-10-01' AND __dt__ <= '2026-10-31'
)
SELECT count(*) FROM t;

参数说明：CTE 会被内联展开，所以外层 month_str = '2026-10' 展开后就是 substr(__dt__,1,7) = '2026-10'——回到了案例 1。这一例真正教的是另一件事：谓词的位置比写法更容易出问题。视图、公共 CTE、被复用的中间层，只要"分区列的原始形态"在传递过程中被丢掉（只投影了派生列），下游使用者无论怎么写都裁不动，而且他不会意识到，因为他看到的 schema 里根本没有分区列。

修复 B 是给"我改不了视图定义"的场景：与其在下游挣扎，不如给视图/CTE 加一个必传参数，或者把中间层落成带分区的小表。

输出表结构：count(BIGINT)。

验收标准：反例与修复版结果一致（约 20 万 ÷ 30 × 31 天口径内当月全部数据，本数据集为 30 个分区全在 10 月，故 ≈ 200000）；files read 上反例 ≈ 30 个分区，修复版同样 30 个——本例的修复版不会少读文件，因为数据只有 10 月。这不是失败：验收看的是 PartitionFilters 是否非空（机制对不对），files read 是否下降（收益有没有）。这两个格子分开填，正是案例 4 教的那条纪律。

5.2.4 一个更靠上游的结论：分区裁剪的天花板

六个案例都在讲"怎么写谓词"。但真正的设计问题是：这张表的分区切得对不对，让裁剪有没有可能存在。

按天分区，20 万车 × 30 天，查"一台车一天"
分区裁剪 ⇒ 命中 1/30 目录 ← 有效
按天分区，查"一个城市一天"
分区裁剪 ⇒ 命中 1/30；城市仍靠列扫描 ← 一半有效，另一半要看 5.3
按天分区，查"一个城市最近 30 天"
分区裁剪 ⇒ 全部命中，等于没裁 ← 失效，但不是谓词写错

第三行是关键：查询模式与分区键不匹配时，谓词写得再正确也裁不动。 这时该改的是 DDL（加一层城市维度分区，或者用 Z-Order 把城市与日期一起编进相关性里，见 5.4），而不是继续折腾 SQL。

前作在 ClickHouse 侧得出过同构结论（ck 第 4 章 4.6：跳过排序键第一列、函数包在键列上，都是"谓词与布局不匹配"），Spark 侧的差别只在于：布局改了要重刷数据，代价更大，所以更需要事前判断。 判断依据就是 5.1.2 那张图的三层：先问这个查询能不能落在某个分区里，再问能不能落到某个桶里，最后才问文件内排序能不能帮忙。

5.2.5 湖表特有的第七件事：分区裁剪发生在"哪一层"

Iceberg 与 Paimon 都自带分区过滤能力，Spark 侧的 PartitionFilters 只是把条件下推给它们。这带来一个 Hive 表没有的行为：候选文件挑选发生在表格式的 planner 里，需要读 manifest / snapshot 元数据。

Hive 目录分区： 谓词 → metastore 分区列表匹配 → 打开目录
Iceberg： 谓词 → 读 snapshot → 读 manifest list → 按 partition 约束
筛 manifest → 按列 min/max 再筛文件 → 才轮到 row-group
Paimon： 谓词 → 读 snapshot → 分区列表 → bucket 定位 → 文件 → DataFile 统计

所以同一条"分区裁剪没生效"的结论，在三种表上的根因位置不同：Hive 是谓词表达问题，Iceberg 可能是元数据缓存问题（前作硬约束：Iceberg 元数据缓存默认 30 秒，结构变更后 Flink 侧需重启会话才立即生效——Spark 侧同样有缓存语义，跨引擎改完立刻查不到新数据要想到这一层），Paimon 可能是 bucket 定位没走等值。

Hive 这一侧还有三个官方开关，解释了"同一句 SQL 在不同环境裁得动/裁不动"的一部分差异（默认值逐字取自 configuration 页）：

读这三行的正确方式："把谓词下推进 metastore 让它早淘汰"和"先把分区名全捞回来再自己筛"是两条路径，前者省的是网络与分区数，后者省的是兼容性问题（复杂谓词、MetaException 退路）。当你的 Hive 分区表突然变慢、或换了 metastore 版本后裁剪行为变了，FastFallback 是第一个该看的地方。另外要破除一个名字：社区文章里流传的 spark.sql.hive.metastore.partition.prune.enabled 不是官方配置名，官方名是上面这个。

这条差异的工程价值：遇到"我明明裁了但没变快"，先问这张表的裁剪发生在哪一层，再决定是改 SQL 还是查元数据。

5.2.6 把观察结果落成版本差异表

六个案例跑完，把与预期不符的条目记下来。这张表是本系列留给读者的填空，也是团队 wiki 上最有用的一页：

5.3 文件级与列级裁剪：分区之后的三层

分区裁掉的是"整个目录"。目录里剩下的，就要靠列式文件自己的统计信息来裁。这一层的能力全部建立在"数据是按某种顺序写的"这个前提上——所以它和 5.4 的排序是一对：5.3 讲尺子，5.4 讲怎么把数据摆到尺子上。

5.3.1 一个 Parquet 文件里有四层可以被裁的东西

demo.parquet
├── row-group #1 ← Iceberg 默认 write.parquet.row-group-size-bytes = 128MB
│ ├── column chunk (vin) 带 statistics：min / max / null_count / value_count
│ ├── column chunk (report_date) 带 statistics
│ └── column chunk (speed)
│ └── page … ← 默认 write.parquet.page-size-bytes = 1MB
│ └── page 级统计（column index / page index）
├── row-group #2
└── footer ← schema + 每个 row-group 每列的统计入口

表 5-3 四层统计、使用方与开关（默认值逐字取自官方页面）

第三行到第四行之间有个必须写清楚的事实：

本次在 Spark 官方文档（sql-data-sources-parquet.html、configuration.html、sql-performance-tuning.html 三页全文）没有找到任何 page index / column index / page-level 的字样，也没有 spark.sql.parquet.columnIndexPageSize 这类配置项。 Parquet 格式本身定义了页级索引，Iceberg 写侧也能生成，但**"Spark 读取时会不会用它裁 page"这件事没有官方依据**，本系列不把它写成事实。需要它时，用 5.3.5 的实测法量给自己看。

同样值得记录的一条取证结论：社区文章里常写的 spark.sql.parquet.recordColumnFilter 不是官方配置名，官方存在的是 spark.sql.parquet.recordLevelFilter.enabled（默认 false，2.3.0 起）。它的一句话描述正好暴露了一个真实取舍：

“If true, enables Parquet’s native record-level filtering using the pushed down filters. This configuration only has an effect when spark.sql.parquet.filterPushdown is enabled and the vectorized reader is not used.”

5.3.2 向量化读取与 record-level filter 互斥，这不是细节

上面那句官方原文里有"and the vectorized reader is not used"。把它和 spark.sql.parquet.enableVectorizedReader = true（2.0.0 起，“Enables vectorized parquet decoding.”）放在一起读，结论是：

默认状态：向量化 reader 开 → record-level filtering 开了也不生效（官方明说）
关掉向量化：能启用 record-level filtering，但退到非向量化解码路径
⇒ 这不是"多开一个开关多一层裁剪"，是一次路径替换

怎么确认自己走的是哪条路：EXPLAIN FORMATTED 里 FileScan parquet 节点有一行 Batched: true/false（第 4 章 4.2 的四个必看标记之一）。Batched: false 就是掉到了非向量化路径——常见诱因是 schema 里有向量化 reader 不支持的类型组合（完整清单本次未逐字取证，按 4.1 Parquet 页核对；车联网表里最容易触发的是 DECIMAL 高精度列与 TIMESTAMP_NTZ 混用）。

判据：同一谓词，分别在 enableVectorizedReader=true（默认）与 false 两种设置下跑，比较 UI 的 scanned rows 与 bytes read。只有当 scanned rows 明显下降时才值得换路径，否则就是拿解码速度换裁剪精度。

5.3.3 字符串列的 min/max 只记前 16 个字符——这对 VIN 意味着什么

Iceberg 官方 write.metadata.metrics.default = truncate(16)（可选 none / counts / truncate(length) / full）。这条默认值直接决定字符串列能不能裁文件：

本数据集的 VIN 形态：LSGKA12P7MA + 6 位数字（第 2 章造数）
前 11 位 = 车型固定前缀，第 12 位起才有区分度
truncate(16) ⇒ 参与统计的是"前缀 + 前 5 位数字" → 区分度足够，能裁

但如果换成：
• 前缀很长的编码（如统一 17 位里只有后 2 位变化） → min/max 区间几乎覆盖全部值 ⇒ 裁不动
• 或者对 URL / 报文文本这类长字符串做前缀过滤 → 同理失效
⇒ 高价值列显式设 full，代价是元数据变大

这条的实用价值在于它能提前解释一种"排序做了但没变快"的现象：你把 city_id（INT）排好了，裁剪生效；但查询走的是 vin LIKE 'LSGKA%' 这种前缀条件，而统计被截断——排序形成的顺序性和统计能表达的边界是两回事。

5.3.4 小文件慢在哪：三个互不相干的代价

很多人把"小文件慢"归因成"文件多"，这只对三分之一。三个代价各自有独立的处置方法：

① 打开成本（每文件一次 IO 突发，与文件大小无关）
官方对分片的估算是把"打开成本"折成字节参与装箱：
spark.sql.files.openCostInBytes = 4194304（4 MB，2.0.0 起）
"The estimated cost to open a file, measured by the number of bytes
that could be scanned in the same time…"
spark.sql.files.maxPartitionBytes = 134217728（128 MB）
⇒ 一个 1KB 的文件在装箱时被当作约 4MB 计 ⇒ 每个 task 仍要打开几十个文件，
每个文件一次 footer 读取（footer 在文件末尾，另一次随机 IO）

② 计划成本（表格式的 planning 时间随文件数线性增长）
Iceberg：manifest 里每个数据文件一行记录 + 若干列统计（表 5-3 第二行那份清单）
⇒ 10 万文件 = 10 万条 entry，planning 与元数据缓存都被推大
⇒ 这正是前作"几千量级分区"经验在文件维度的另一半：分区数管目录，文件数管 manifest

③ 解码成本（向量化 reader 按批解码）
向量化路径的收益来自"一次处理一批行"；小文件往往凑不满一批，
批的边界与文件边界反复对齐，退化明显
⇒ 具体批大小配置名本次未逐字取证，判据看实测：bytes read 相近但耗时差一个量级，
基本就是这一项

治理入口只有一个，参数有三个（Iceberg 1.12 官方默认值，逐字）：

这张表解释了生产上最常见的困惑：“我跑了 rewrite_data_files，文件数没变”。默认参数下它只处理 小于 384MB（512×75%）且同组不少于 5 个 的文件——10 万个小文件当然会被合并，但 3 个 600MB 的文件不会被动。要改行为就显式传参，不要指望默认值。 第 10 章会给完整的维护作业编排。

5.3.5 观测列级裁剪：三件套加一次对照实验

— 主实验：同一张表，两个谓词分别打在"参与排序的列"与"不参与任何布局的列"上
— 前置：本实验用的表在 5.4.3 建，先跑 5.4 再回来做这一项也可以（顺序不影响结论）
EXPLAIN FORMATTED
SELECT vin, speed FROM iceberg.demo.dwd_vehicle_telemetry
WHERE city_id = 310007; — (a) 参与排序/统计的列

EXPLAIN FORMATTED
SELECT vin, speed FROM iceberg.demo.dwd_vehicle_telemetry
WHERE battery_pct = 42; — (b) 不参与排序的列（基数低、散布全表）

参数说明：两个谓词都是等值、都只引用单列，因此都能被下推（PushedFilters 都会非空）。差别只在统计边界能不能给出"这一块一定不匹配"的结论。(a) 若数据按 city_id 排过，块级 min/max 很窄；(b) battery_pct 在每个块里都取遍 10~99，min/max 永远覆盖 42，一个块都跳不掉。这正是"谓词下推生效 ≠ 数据被裁掉"的成因，也是第 4 章五问模板第 2 问要看得比 PushedFilters 更细的原因。

输出表结构：vin(STRING), speed(FLOAT)。

验收标准：两条 SQL 的 PushedFilters 都非空；差别必须体现在运行后的数字上——(a) 的 scanned rows 应显著低于 (b)。如果 (a) 也没降，回到 5.4 检查排序是否真的落到了文件上（历史数据不会因为改了一条 ALTER … WRITE ORDERED BY 而重排）。

另外两个官方"能减少扫描"的开关，务必和文件级裁剪区分开：

把 runtime bloom filter 当成"文件裁剪"来期待，是社区文章里流传最广的误读。官方原文写的是 reduce shuffle data。要验证它对扫描有没有帮助，只看 files read 有没有变——默认它不会变。

5.4 排序、聚簇与 Z-Order：把数据摆到尺子上

5.3 讲的是尺子（统计边界）。这一节讲怎么让数据摆得"有边界"。先破一个语法幻觉，再讲选型，最后给可跑的三段 SQL。

5.4.1 Spark 没有"写入时排序"的 SQL 写法

本次取证里最反直觉的一条：

官方 INSERT 语法页（sql-ref-syntax-dml-insert-into.html）的 Syntax 全文：
INSERT INTO [ TABLE ] table_identifier [ partition_spec ] [ ( column_list ) ]
{ VALUES ( … ) | query }
→ 整页 0 次出现 ORDER BY / SORT BY / CLUSTER BY / DISTRIBUTE BY

官方 SELECT 页对 ORDER BY 的原文只有一句定位：
"Specifies an ordering of the rows of the complete result set of the query.
The output rows are ordered across the partitions."
→ 它描述的是查询输出，不是落盘布局

那"排序写入"到底由谁决定？官方把它放在 DataSource V2 的接口层，两条原文说完了整件事：

“A Write implementation can also implement RequiresDistributionAndOrdering to tell Spark how input data must be distributed and sorted before writing. Spark will insert shuffle and sort nodes as needed to satisfy these requirements.”

“Requested distribution and ordering — Write connectors can request that Spark repartition and sort incoming data before writing, enabling optimized data layouts such as clustering or Z-ordering.”

结论说得直白一点：写入布局的排序能力是 connector 向 Spark 申请的，不是用户在 SQL 里写 ORDER BY 换来的。 所以本章后面所有"怎么排"的语法都来自表格式自己的扩展，而不是 Spark SQL：

• Iceberg 提供 SQL 扩展模块（官方原文：Iceberg 0.11.0 起为 Spark 增加扩展命令，如 CALL 与 ALTER TABLE … WRITE ORDERED BY），有 WRITE ORDERED BY / WRITE LOCALLY ORDERED BY / WRITE UNORDERED / WRITE DISTRIBUTED BY PARTITION 四条。
• Paimon 把布局交给维护过程：append 表的 incremental clustering，以及 CALL sys.compact(… order_strategy => 'zorder', order_by => …)。
• Hive 风格表用 DDL 子句 CLUSTERED BY … SORTED BY … INTO n BUCKETS（官方原文：“Bucketing is an optimization technique that uses buckets (and bucketing columns) to determine data partitioning and avoid data shuffle.”），见 5.5。

表 5-4 五种"排序"能力对照（官方定位逐字摘）

最后一列那句话值得单独抄进评审清单：WRITE ORDERED BY 改的是"以后怎么写"，不是"已经写好的怎么摆"。 存量数据只有 rewrite 一条路。生产上最常见的错法是"给表加了排序，然后发现查询没变快"——顺序全对，只是没人重写历史文件。

5.4.2 线性 / Z-Order / Hilbert：按查询形态选，不按名气选

两个维度（横轴 city_id、纵轴 report_date）的两种摆法：

线性排序 sort(city_id, report_date)
┌─────────────────────────────────┐ city 先分组，组内按日期连续
│ ██│▓▓│░░│──│── │ · 查 city=? ⇒ 1 段连续块，极好
│ ██│▓▓│░░│──│── │ · 查 date=? ⇒ 每段各沾一点，几乎全读
│ ██│▓▓│░░│──│── │ · 查 city=? AND date=? ⇒ 1 块内定位，极好
└─────────────────────────────────┘ · 优点：单维选择性最强，代价最小
██=city1 ▓▓=city2 ░░=city3

Z-Order（city 与 date 的比特位交错）
┌─────────────────────────────────┐ 空间上相邻的格子在编码上也相邻
│ A│B│A│C│B│A│C│B │ · 查 city=? ⇒ 若干块，能裁
│ ─┼─┼─┼─┼─┼─┼─┼─ │ · 查 date=? ⇒ 若干块，能裁
│ D│B│D│C│B│D│C│A │ · 查 city=? AND date=? ⇒ 1~2 块，好
└─────────────────────────────────┘ · 代价：没有任何一维拿到"连续整段"
同一字母 = 编码上相邻的块 多维各自都只拿到"部分收益"

Hilbert：与 Z-Order 同族，局部性保持更好，维度多时优势显现

表 5-5 三种布局对不同查询形态的表现（笔者归纳，判据见 5.6 实测）

官方给出的选型规则（比任何口诀都可信）：Paimon 的 clustering.strategy 默认 auto，官方逐字说明是 “Automatic selection uses order for one column, zorder for two to four, and hilbert for five or more.” —— 1 列线性、2~4 列 Z-Order、5 列以上 Hilbert。Iceberg 侧则在 rewrite_data_files 的 sort_order 里同时提供 zorder(c1,c2,c3) 与 hilbert(c1,c2,c3) 两种写法。超过四列还在往 Z-Order 里塞，就已经越出官方建议区间了。

落到车联网这条链路上，两个真实需求给出两个相反的答案：

需求 A：诊断/客服"查一台车某一天的轨迹"
查询形状：vin = ? AND report_date = ? （两列都是等值，且几乎总是同时出现）
选择：线性 WRITE ORDERED BY (vin, report_date)
理由：线性对"复合等值 + 组内范围"是最优形状；换 Z-Order 会让同一 vin 的数据
不再连续，反而牺牲了"按车整段导出"这类作业

需求 B：城市运营看板"任意城市 × 任意日期区间"
查询形状：city_id 可能有、date 范围几乎总有，且 city 常常单独出现
选择：分区裁日期 + Z-Order(city_id, report_date) 整理块内相关性
理由：city 不在分区键里，线性排序对"只给 city"零收益；Z-Order 是唯一能同时
照顾两维的手段

需求 C：把两者都想要的表
答案：不存在一个布局能同时最优。这时该拆表（DWD 明细按 vin 排、DWS 城市汇总
按 city 排），不是继续调排序参数。这是本章对"过度优化"最重要的一条劝阻。

两条必须一起说出来的代价，否则读者会以为 Z-Order 免费：

5.4.3 实操：从建表到重写历史数据

— 文件：zorder_layout.sql
— ① 建 DWD 明细表：分区与排序分开写，两件事各管一段
CREATE TABLE IF NOT EXISTS iceberg.demo.dwd_vehicle_telemetry (
vin STRING,
city_id INT,
report_date DATE,
reported_at TIMESTAMP,
speed FLOAT,
battery INT,
battery_pct TINYINT,
vehicle_status STRING,
seq BIGINT,
__dt__ STRING
) USING iceberg
PARTITIONED BY (days(report_date))
TBLPROPERTIES (
'format-version' = '2',
'write.target-file-size-bytes' = '33554432', — 32MB：实验规模必须切小，理由见下
'write.parquet.row-group-size-bytes' = '4194304' — 4MB：让 row-group 级裁剪可观测
);

— ② 表级全局排序（对"新写入"与"MERGE INTO"生效）
ALTER TABLE iceberg.demo.dwd_vehicle_telemetry
WRITE ORDERED BY city_id, report_date, vin;

— ③ 或者：task 内局部排序，省掉一次全局 shuffle（②③互斥，实际只保留一条）
ALTER TABLE iceberg.demo.dwd_vehicle_telemetry
WRITE LOCALLY ORDERED BY city_id, vin;

— ④ 取消表级排序
ALTER TABLE iceberg.demo.dwd_vehicle_telemetry WRITE UNORDERED;

— ⑤ 写入历史数据（第 2 章数据集整段搬入，保持可复现）
INSERT INTO iceberg.demo.dwd_vehicle_telemetry
SELECT vin, city_id, report_date, reported_at, speed, battery, battery_pct,
vehicle_status, seq, __dt__
FROM paimon.demo.ods_vehicle_telemetry
WHERE __dt__ BETWEEN '2026-10-01' AND '2026-10-30';

参数说明

输出表结构：与源列一致（10 列）。report_date 是 DATE，隐藏分区字段 report_date_day 不出现在 schema 里。

验收标准

SELECT count(*) AS rows_total, count(DISTINCT vin) AS vin_cnt,
min(report_date) AS dmin, max(report_date) AS dmax
FROM iceberg.demo.dwd_vehicle_telemetry;
— 期望：200000 / 200000 / 2026-10-01 / 2026-10-30，与第 2 章 ODS 完全一致

SELECT file_format, record_count, file_size_in_bytes
FROM iceberg.demo.dwd_vehicle_telemetry.files
ORDER BY file_size_in_bytes DESC;
— Spark 侧元数据表用点号 .files（前作硬约束：Flink 侧要写 $files，两者不可混用）
— 期望：文件数 ≥ 2；每个文件 record_count 与 file_size_in_bytes 相互匹配（无极端长尾文件）

历史数据的布局只能重写。rewrite_data_files 在 Iceberg 1.12.0 的参数与旧版差别很大，这是本章最需要"按版本核对"的一段：

— ⑥ 对历史数据做 Z-Order 重排（1.12 的参数名）
CALL iceberg.system.rewrite_data_files(
table => 'demo.dwd_vehicle_telemetry',
strategy => 'sort',
sort_order => 'zorder(city_id, report_date)',
where => "report_date >= '2026-10-01'",
options => map('target-file-size-bytes', '8388608',
'max-concurrent-file-group-rewrites', '5')
);

— ⑦ 只合并小文件，不动顺序
CALL iceberg.system.rewrite_data_files(
table => 'demo.dwd_vehicle_telemetry', strategy => 'binpack');

— ⑧ 看结果：文件数与每文件行数
SELECT count(*) AS file_cnt, sum(record_count) AS rows_total,
avg(file_size_in_bytes) AS avg_bytes
FROM iceberg.demo.dwd_vehicle_telemetry.files;
— 验收：rows_total 必须与⑤前后一致（rewrite 不删行）；file_cnt 变化符合 target 设定

表 5-6 rewrite_data_files 参数与官方默认值（Iceberg 1.12.0，逐字）

这张表里最容易写错的是参数名。 旧版教程里常见的 sort_by / zorder_by / distribute_by / sort_buffer_size，在本次 1.12.0 的 rewrite_data_files 文档里出现次数为 0（sort_by 只存在于 rewrite_manifests，语义是"按分区变换名 cluster manifest"）。照旧版参数名写，会直接报找不到参数——这不是兼容性问题，是版本基线不同。 第 10 章的维护作业一律按这张表写。

where 那句 “all files that may contain data matching” 也要单独记住：它是候选文件筛选，不是行过滤。rewrite 不会减少任何行，谁要是以为 where 能"清理旧数据"，就会在跑完之后发现数据还在——而真正的清理是 DELETE + expire（第 10 章）。

5.4.4 与 ClickHouse 稀疏索引对照：裁剪粒度差多少

前作 ck 第 3/4 章取证过 ClickHouse 的机制：ORDER BY 排序键即主键前缀，part 内严格有序，mark 每 index_granularity（默认 8192）行一条，二分定位 granule。对照湖表：

表 5-7 ClickHouse 稀疏索引 vs 湖表排序裁剪

一句话概括这个对照（笔者归纳，非官方措辞）：

ClickHouse 的排序"就是"索引；湖表的排序"喂给"统计信息。前者省的是行区间，后者省的是文件与块。 所以同一句 sort(city_id, vin)，在 CK 上你能指望 8192 行的精度，在湖表上你的精度单位是"一个几百 MB 的文件里有几段窄边界"——除非你把文件切小到几十 MB，而那就等于亲手制造小文件问题。

这条对照的直接工程后果，是本章给湖表定的一个务实起点：

湖表不要追求 granule 级细粒度。
目标 = 每个文件/块内的 city、日期高度同质，且文件总数可控。
常见落点：文件 32~128MB、row-group 用默认或折半、分区按天、
排序列不超过 3~4 个（超出就回到官方 auto 规则：2~4 用 zorder，≥5 用 hilbert）
反例：为了让"查一台车"更快，把 target 设成 2MB ⇒ 文件数 ×250，
manifest 与 planning 先炸，第 10 章来收拾你

5.5 Bucket：三个引擎同一个词，三种语义

"分桶"是全系列最容易让人把不同东西当成同一件事的词。第 4 章讲过 Spark 的 join 策略选择，前作在 Doris 侧定过 Colocate Join 的硬约束（同分桶列、同桶数、同 colocate group），第 2 章又给 Paimon 表写了 'bucket' = '4'。三个"桶"的目的完全不同，把它们当同一个东西，就会在错误的场景期待错误的收益。

5.5.1 三套 bucket 的语义对照

表 5-8 三种 bucket 对照

三条必须说透的差异：

① Iceberg 的 bucket 不是"桶"，是"分区"。 bucket(16, vin) 出现在 partition spec 里，产出的 vin_bucket=7/ 与 report_date_day=2026-10-15/ 是同一层级的东西。所以它的代价也按分区算：16 个桶 × 30 天 = 480 个分区目录。这就是为什么 Iceberg 侧选桶数要拿"几千量级分区"这把尺子量，而不是拿"并行度"这把。

② Paimon 的桶是"正确性约束"，不只是性能选项。 官方那句话把因果讲完了：“For primary-key tables, bucket-key defaults to the primary key excluding partition columns.” —— 默认桶键就是"主键去掉分区列"。把它和第 2 章那条硬约束（Paimon 主键必须包含全部分区字段）放在一起读，结论很清楚：分区字段负责把数据切到目录，剩下的主键部分负责定桶，两者拼起来才是完整主键。谁手动指定了一个与主键不一致的 bucket-key，谁就在制造"同键不同桶"的风险。

还有一个读者一定会撞上的差异：Paimon 官方默认是动态桶（bucket = -1），而第 2 章的 ODS 表显式写了 'bucket' = '4'（固定桶）。 这是刻意安排的——实验要的是可预期的目录形态。生产上选固定桶意味着接受官方那句 “resizing requires an explicit rescale operation”；选动态桶意味着接受 “Index memory and single-writer constraints”（索引占内存、单写者约束）。这两个代价必须在建表评审时写下来，不能等到改桶数那天才发现。

③ Hive bucket 是唯一能带来"免 shuffle"的，但它有前置门槛。 Spark 侧要认出这个性质，需要：分桶信息在 catalog 里可见，且 spark.sql.sources.bucketing.enabled 处于开启（官方默认 true，2.0.0 起；原文措辞很有画面感——“When false, we will treat bucketed table as normal table”），另有上限 spark.sql.sources.bucketing.maxBuckets = 100000（2.4.0 起）。少任何一条，收益静默归零——计划里 Exchange 一个不少，而且没有任何警告。

5.5.2 免 shuffle 这件事：先验证，再期待

— 前置检查 1：分桶优化开关在不在（官方默认 true）
SET spark.sql.sources.bucketing.enabled;
— 输出列：key(STRING), value(STRING)
— 若被某处配置成 false，官方行为是"把分桶表当普通表"——收益直接归零且不报错

— 前置检查 2：桶上限
SET spark.sql.sources.bucketing.maxBuckets; — 官方默认 100000

— 前置检查 3：当前 catalog 能否持久化分桶元数据
SET spark.sql.catalogImplementation;
— 说明：官方 CREATE TABLE 的两个页面都接受 CLUSTERED BY 子句——
— Hive 风格：sql-ref-syntax-ddl-create-table-hiveformat.html
— DataSource 风格：sql-ref-syntax-ddl-create-table-datasource.html
— 官方原文示例逐字为：CREATE TABLE student (id INT, name STRING, age INT)
— USING CSV PARTITIONED BY (age) CLUSTERED BY (Id) INTO 4 buckets;
— 两种写法都能建，差别在"桶信息写进哪份元数据、能不能被下次会话读回来"。
— 建完立刻 DESCRIBE EXTENDED 看一眼，比背语法可靠。

— 文件：partition_design.sql 的第 3 段
— 官方两种 DDL 形态都接受 CLUSTERED BY；生产上推荐落进能持久化桶信息的 catalog（接 HMS 的 spark_catalog）
CREATE TABLE IF NOT EXISTS spark_catalog.demo.bkt_telemetry (
vin STRING,
report_date DATE,
reported_at TIMESTAMP,
city_id INT,
speed FLOAT,
battery INT,
vehicle_status STRING,
seq BIGINT
)
USING parquet
CLUSTERED BY (vin) — 桶键：join 键，必须与下游查询的等值列一致
SORTED BY (vin, reported_at) — 桶内排序：让"按车取时序"免一次 sort
INTO 8 BUCKETS — 8 = 2 的幂，便于与并行度对齐
PARTITIONED BY (report_date);

— 灌数：直接演示"同桶键同桶数"的第二张表（聚合结果表，用于 join）
CREATE TABLE IF NOT EXISTS spark_catalog.demo.bkt_vehicle_daily (
vin STRING,
report_date DATE,
trip_cnt BIGINT,
avg_speed DECIMAL(10,3)
)
USING parquet
CLUSTERED BY (vin) INTO 8 BUCKETS
PARTITIONED BY (report_date);

参数说明（只讲容易误解的两处）

桶数怎么定（口径要分清）

Hive / Paimon 侧：按"单桶数据量"反推
桶数 ≈ 单个分区的字节量 ÷ 目标单桶大小
Paimon 官方口径（逐字）："For MOR workloads, 200 MB–1 GB per bucket is
an initial sizing guide, not a limit. Measure skew, throughput, and read
plans to select the actual count."
⇒ 一个分区 4GB、目标 512MB ⇒ 8 桶
⇒ 注意官方紧接着的那句："A batch scan can split one bucket into
independent key ranges, so bucket count is not a hard read-parallelism cap."
这句直接否掉了"桶数 = 读并行度"的常见误解（见 5.5.4）

Iceberg 侧：按"总分区数"反推
总分区数 ≈ 时间分区数 × bucket(n) 的 n
受"几千量级分区"约束 ⇒ n 的上界由时间分区数决定
⇒ 30 天 × n ≤ 几千 ⇒ n 可以很大；但 1000 天 × n 就必须把 n 压到个位数

"几千量级分区"这条尺子要说清来源：它是前作 Iceberg 系列定下的工程口径，本次在 Iceberg 1.12.0 的 partitioning 文档全文里没有检索到对应措辞（官方页面只讲 transform 列表、分区演进与"plan 只读匹配分区"的收益）。所以它的性质是工程经验，不是官方规范——用于评审提问很有用，用于"引用官方"不行。

输出表结构：bkt_telemetry 为分桶 + 分区表，物理上 report_date=2026-10-15/000000_0.parquet … 每分区 8 个桶文件（Spark 写 Hive 风格分桶表时，文件名里的编号承载桶号；具体形态随版本而异，验收不看文件名）。

验收标准

— 关键验收：join 的 Exchange 有没有少
EXPLAIN FORMATTED
SELECT t.vin, t.report_date, t.speed, d.avg_speed
FROM spark_catalog.demo.bkt_telemetry t
JOIN spark_catalog.demo.bkt_vehicle_daily d
ON t.vin = d.vin AND t.report_date = d.report_date;
— 判定表：
— | 观察 | 结论 |
— | join 两侧均无 Exchange hashpartitioning(vin, N) | 分桶对齐生效，免 shuffle |
— | 两侧各多一个 Exchange hashpartitioning(vin, 200) | 收益归零：桶数不同 / 开关未开 / 桶信息未被识别 |

为什么"归零"要写成一条纪律：免 shuffle 失效时 Spark 不报错、不打警告，计划退化得无声无息。唯一的发现手段是对比 Exchange 数量——所以这条 SQL 应该在改桶数、升级 Spark、换 catalog 之后各跑一次，把结果存档。

5.5.3 与 Doris Colocate Join 的不等价性（回扣前作）

前作硬约束：Colocate Join 要求同分桶列、同桶数，并且要配置 Colocate Group。Spark 侧的分桶 join 表面像，实质差三点：

最关键的一句：Spark 的 bucket 只保证"不需要重排"，不保证"数据在本地"。 所以拿 Doris 的 colocate 直觉去设计 Spark 湖表，会期待一个不存在的收益。

而且——湖表这一侧确实有一个官方机制，但它的名字和适用范围与多数人的想象不同：

Storage Partition Join（SPJ），官方逐字：“Storage Partition Join (SPJ) is an optimization technique in Spark SQL that makes use of the existing storage layout to avoid the shuffle phase. This is a generalization of the concept of Bucket Joins, which is only applicable for bucketed tables, to tables partitioned by functions registered in FunctionCatalog. Storage Partition Joins are currently supported for compatible V2 DataSources.”

对应开关：spark.sql.sources.v2.bucketing.enabled = true（3.3.0 起），官方描述 “When true, try to eliminate shuffle by using the partitioning reported by a compatible V2 data source.”

它还在被修：Spark 4.1.0 发布说明里有 [SPARK-53074] Avoid partial clustering in SPJ to meet a child's required distribution。

这段原文纠正了一个流传很广的说法——"只有 Hive 分桶表才能免 shuffle"已经不成立：官方明说 SPJ 是 Bucket Join 的泛化，适用到"按注册在 FunctionCatalog 里的函数分区"的表，而这正是 Iceberg 隐藏分区（days(…)、bucket(N, col)）的形态。

但它同时给了两个限制条件，两个都很容易被人跳过：

① "compatible V2 DataSources" ——兼容是连接器的事，不是 Spark 的承诺
② "partitioning reported by" ——连接器必须真的把分区信息上报给 Spark
⇒ 所以 Iceberg / Paimon 在你这套版本组合上到底能不能吃到 SPJ，
是一个"实测项"，不是一个"背下来的结论"。本次未取证连接器侧的上报实现。

实测只有一条判据（就是 5.5.2 验收里那条，这里再强调一次它的普适性）：把 join 两侧都换成湖表，EXPLAIN FORMATTED 里数 Exchange。消失了就是生效了，没消失就是没生效——不要引用任何人的博客代替这一步，包括本系列的。

因此生产上的可行组合仍然是三条，只是第①条的措辞变了：

① 热点大表之间的高频 join，且能接受重刷代价
→ 首选 Hive 风格分桶表（两侧同桶键同桶数），这是官方明确承诺的路径；
湖表则先实测 SPJ 是否生效，生效才写进设计，不生效不要当既成事实
② 大表 × 小表
→ 不要指望分桶。走广播（第 4 章 BHJ），或把小表做成 Broadcast 变量/位图
③ 大表 × 大表且都是湖表，且 SPJ 实测不生效
→ 接受一次 shuffle，用 AQE 控并行度 + 两阶段聚合缓解倾斜（4.5.3）

车联网链路里真实出现的形态是"轨迹大表 × 车辆日汇总大表"，两者都是 Iceberg。这条链路上，分桶收益在未实测前一律按"没有"来设计——把 SPJ 实测列进 DDL 评审清单，比留一个"理论上能免 shuffle"的期待有用得多。

5.5.4 一个必须说的反例：桶数与并行度不是一回事

误解：8 个桶 ⇒ 查询并行度 8
事实：读侧 task 数由文件分片决定（spark.sql.files.maxPartitionBytes、
openCostInBytes、AQE 合并），桶只是"文件归属规则"
后果：桶数设成 8 但每桶文件很小 ⇒ 实际可能 1 个 task；
桶数设成 8、数据 100GB ⇒ 每个桶一个 12GB 文件 ⇒ 单 task 长尾，AQE 治不了读侧（4.3 边界）

前作在 SeaTunnel 侧有一条同构经验（JDBC 切分列必须是索引列，否则并行 SQL 反而更慢）——"能并行"和"并行得有效"是两件事。桶数、分区数、shuffle.partitions 是三个独立旋钮，只有 5.5.2 那种"计划里数 Exchange"的实测能把它们的关系确认下来。

5.6 四层裁剪漏斗的 Spark 版本

到这里可以把四层重新排一遍，并给每一层一个能填数字的格子。这张图就是 ck 第 4 章那张漏斗的 Spark 对应物——形状一样，名字不同。

你的 SQL 的 WHERE 条件
│
▼
┌────────────────────────────────────────────────────────────────┐
│ 第 1 层 分区裁剪（目录 / partition spec） │
│ 谁来裁 Spark + 表格式 planner + metastore │
│ 拿什么裁 分区值（Hive/Paimon）或 transform 域约束（Iceberg） │
│ 观测 partitions read / EXPLAIN 的 PartitionFilters 非空 │
│ 省掉 整个目录的 list + 元数据 + IO ★收益最大 │
└──────────────────────────┬─────────────────────────────────────┘
▼ 剩下的候选文件
┌────────────────────────────────────────────────────────────────┐
│ 第 2 层 文件裁剪（列统计 lower/upper bounds、value/null counts）│
│ 谁来裁 Iceberg planner（读 manifest 时就裁）/ Paimon scan │
│ 拿什么裁 每文件每列的统计（字符串默认只记前 16 字符） │
│ 观测 files read：候选文件数 vs 实际打开数 │
│ 省掉 不打开文件（连 footer 都不读） │
└──────────────────────────┬─────────────────────────────────────┘
▼ 打开的文件
┌────────────────────────────────────────────────────────────────┐
│ 第 3 层 row-group / 块裁剪（Parquet column chunk 的 min/max） │
│ 谁来裁 Parquet reader（谓词下推） │
│ 开关 spark.sql.parquet.filterPushdown = true（官方默认） │
│ 观测 row groups read：Selected / Missing / Total │
│ 省掉 块级 IO；列只读需要的（ReadSchema 列裁剪） │
│ ★page 级：Spark 官方无对应开关，本页不写成事实（见 5.3.1） │
└──────────────────────────┬─────────────────────────────────────┘
▼ 读进内存的行
┌────────────────────────────────────────────────────────────────┐
│ 第 4 层 行级过滤 + 列裁剪（真正的 WHERE 求值） │
│ 谁来裁 Spark（向量化批内 / 非向量化 record-level filter） │
│ 观测 scanned rows → output rows；bytes read │
│ 到这一层才"精确"，但前三层决定了你要付多少钱走到这里 │
└────────────────────────────────────────────────────────────────┘

图 5-2 四层裁剪漏斗与每层的观测指标

表 5-9 每层的名字、开关与"不合格"的样子

5.6.1 四态实验：同一份数据摆成四种布局

这一步是整个系列的"裁剪天花板"实验，也是本章唯一需要你自己填数字的地方。 之所以不给现成结论，是因为文件数、块数强依赖版本与连接器实现——填进去的每一格都必须是你在自己环境里量出来的，这也是本章反复强调的纪律。

— 文件：partition_design.sql 的第 4 段（四态对照表）
— 四张表都从第 2 章 ODS 派生，数据完全相同，只有物理布局不同

— S0：裸表（无分区、无排序、默认 512MB 目标）
CREATE TABLE IF NOT EXISTS iceberg.demo.t_layout_raw (
vin STRING, city_id INT, report_date DATE, reported_at TIMESTAMP,
speed FLOAT, battery INT, battery_pct TINYINT, vehicle_status STRING, seq BIGINT
) USING iceberg TBLPROPERTIES ('format-version'='2');

— S1：加分区
CREATE TABLE IF NOT EXISTS iceberg.demo.t_layout_part (
vin STRING, city_id INT, report_date DATE, reported_at TIMESTAMP,
speed FLOAT, battery INT, battery_pct TINYINT, vehicle_status STRING, seq BIGINT
) USING iceberg PARTITIONED BY (days(report_date))
TBLPROPERTIES ('format-version'='2',
'write.target-file-size-bytes'='33554432', 'write.parquet.row-group-size-bytes'='4194304');

— S2：加分区 + 表级排序（与 S1 只差一条 ALTER 的时机）
CREATE TABLE IF NOT EXISTS iceberg.demo.t_layout_sort (
vin STRING, city_id INT, report_date DATE, reported_at TIMESTAMP,
speed FLOAT, battery INT, battery_pct TINYINT, vehicle_status STRING, seq BIGINT
) USING iceberg PARTITIONED BY (days(report_date))
TBLPROPERTIES ('format-version'='2',
'write.target-file-size-bytes'='33554432', 'write.parquet.row-group-size-bytes'='4194304');
ALTER TABLE iceberg.demo.t_layout_sort WRITE ORDERED BY city_id, report_date, vin;

— S3：与 S1 相同布局，但事后做 Z-Order 重写（先灌数再 rewrite）
CREATE TABLE IF NOT EXISTS iceberg.demo.t_layout_zorder (
vin STRING, city_id INT, report_date DATE, reported_at TIMESTAMP,
speed FLOAT, battery INT, battery_pct TINYINT, vehicle_status STRING, seq BIGINT
) USING iceberg PARTITIONED BY (days(report_date))
TBLPROPERTIES ('format-version'='2',
'write.target-file-size-bytes'='33554432', 'write.parquet.row-group-size-bytes'='4194304');

— 灌数（四张表同一段 SELECT，字段列表显式写全，避免列序串位）
INSERT INTO iceberg.demo.t_layout_raw
SELECT vin, city_id, report_date, reported_at, speed, battery, battery_pct, vehicle_status, seq
FROM paimon.demo.ods_vehicle_telemetry;
— 其余三张表重复同一段，只在 t_layout_zorder 灌完后执行：
CALL iceberg.system.rewrite_data_files(
table => 'demo.t_layout_zorder', strategy => 'sort',
sort_order => 'zorder(city_id, report_date)');

参数说明：为什么 S0 不设小 target、S1~S3 设成 32MB/4MB？因为对照实验必须让"布局"成为唯一变量。S0 一个 512MB 目标下只有 1 个文件，它的 files read 恒为 1——这本身就是最有说服力的一格：文件都只有一个，谈不上文件级裁剪。

输出表结构：四张表列结构完全一致（9 列），行数完全一致（200000）。

验收标准（三条必须全过，否则四态对比无效）

SELECT 'raw' AS st, count(*) AS c FROM iceberg.demo.t_layout_raw
UNION ALL SELECT 'part', count(*) FROM iceberg.demo.t_layout_part
UNION ALL SELECT 'sort', count(*) FROM iceberg.demo.t_layout_sort
UNION ALL SELECT 'zorder', count(*) FROM iceberg.demo.t_layout_zorder;
— 四行必须完全相等
SELECT 'zorder' AS st, count(*) AS f, sum(record_count) AS r FROM iceberg.demo.t_layout_zorder.files;
— r 必须等于 200000（rewrite 不删行）

两个探针查询，分别代表两类真实需求：

— Q1：需求 A 形态（时间 + 城市都有）——分区就该帮忙
SELECT count(*) FROM <state_table> WHERE report_date = DATE '2026-10-15' AND city_id = 310007;
— Q2：需求 B 形态（只给城市，跨全月）——分区无能为力，只能靠第 2/3 层
SELECT count(*) FROM <state_table> WHERE city_id = 310007;

5.6.2 量出来：measure_scan.py

Spark 的 EXPLAIN 不给实测（第 4 章 4.2 那条不对称），实测只能从事件日志拿。第 2 章已经把 spark.eventLog.enabled 打开了，这里直接用它——这就是为什么事件日志要在搭环境的第一个小时就开，而不是等到第一次排障。

# 文件：measure_scan.py
# 用法：spark.eventLog.enabled=true 跑完查询后，对生成的事件日志执行
# python measure_scan.py /data/spark/eventlog/local-xxx.log
# 依赖：仅标准库
import json, sys, re

def collect(path):
"""从事件日志里抓每个 SQL execution 的累加器指标。"""
accs, sqls = {}, []
for line in open(path, encoding="utf-8"):
try:
e = json.loads(line)
except json.JSONDecodeError:
continue
t = e.get("Event")
if t == "SparkListenerSQLExecutionStart":
sqls.append((e["executionId"], e.get("description", "")))
elif t == "SparkListenerSQLAccumulator":
m = e.get("metric", {}) or {}
acc = e.get("accumualtorUpdate") or e.get("accumulatorUpdate") or {}
name = m.get("name") or ""
typ = m.get("type") or ""
val = m.get("value")
if val is None:
val = acc.get(e.get("accumualtorId", ""), None)
key = (e.get("sqlExecutionId"), name, typ)
accs[key] = accs.get(key, 0) + (val if isinstance(val, (int, float)) else 0)
return sqls, accs

# 关心的指标名（不同版本命名略有差异：先跑一次看它到底叫什么）
PATTERN = re.compile(r"(file|row group|page|scan|record|bytes|partitions)", re.I)

sqls, accs = collect(sys.argv[1])
for eid, desc in sqls:
print(f"\\n=== SQL {eid} :: {desc[:110]}")
for (seid, name, typ), v in sorted(accs.items()):
if seid == eid and PATTERN.search(name or ""):
print(f" {name:<38} {typ:<12} {v}")

参数说明：事件日志里 SQL 指标的字段名在各版本间确有差异（accumualtorUpdate 这个拼写是官方事件日志里历史遗留的笔误，脚本对新旧两种写法都做了兼容尝试——这也是"日志格式不要靠猜"的一个具体例子）。所以脚本的策略是先把你环境里所有名字里带 file/row group/page/scan/record/bytes 的指标全打出来，再人工认哪一个是"文件数"。这是有意的：背指标名不如认出指标名。

输出结构：每条 SQL 一段，逐行 指标名 / 类型 / 累加值。

验收标准：能稳定打出四个数字——文件数、row-group 数（Selected/Total 或等价项）、scanned rows、bytes read。四个都拿不到就先去第 17 章（可观测落地），别用估算数字代替实测。

5.6.3 记录表：把它填成团队的第一份基线

表 5-10 四态实测记录（本系列不代填数字）

填完后你会得到三个结论，它们比任何一段说明都有用：

① S1 对 Q1 有效、对 Q2 无效 ⇒ 分区只裁它切的那个维度，别指望它顺手裁别的
② S2 与 S1 的差，就是"排序"的净值 ⇒ 净值为 0 时，说明文件太宽或统计太糙（回 5.3.3/5.3.4）
③ S3 与 S2 的相对高低决定选型 ⇒ 你的真实查询里"只给 city"占多少？
占比低就留线性，别为了 Q2 牺牲 Q1 和流式导出

实验规模不足时的现象要提前知道：20 万行数据即使切成 32MB 也只有 1~2 个文件，S2/S3 的差别可能量不出来。这不是实验失败，是你的数据没到需要裁剪的规模。 想看到差别，把第 2 章的 sequence(1, 200000) 改成 sequence(1, 20000000) 重灌一遍（造数原则不变：全部从 v 派生，禁止 rand()），或者把 target 进一步降到 4MB。记住方向：实验时把文件切小是为了看清机制；生产时把文件合大才是省钱。

工程要点

本章小结

这一章把"少读数据"落成了三段可执行的话：分区定目录、分桶定文件、排序定块。

• 5.1 用表 5-1 钉住三种"分区"的差别，核心不是语法，而是谁负责裁剪——Hive 是 Spark，Iceberg 是表格式 planner，Paimon 是分区 + 桶两级定位。图 5-1 给出三件事各管哪一段物理布局。
• 5.2 给了六个失效案例和一张速查表。两个必须带走的习惯：结论由 files read 给，不由 EXPLAIN 给；格式不一致会返回空而不是返回慢，所以断言要无条件加。
• 5.3 数清了四层统计，也数清了 Spark 官方真正给了开关的只有三层——page 级在官方文档里找不到任何配置项，本章不把它写成事实。附带一条硬事实：向量化读取与 record-level filtering 互斥。
• 5.4 破掉"写入时排序"的语法幻觉，把选型规则交给官方区间（1 列线性 / 2~4 列 Z-Order / 5 列以上 Hilbert），并给了一次真实对照：ClickHouse 的排序是索引本身，湖表的排序只是喂给统计的信息，精度单位的差别决定了不要拿 granule 的思路去切湖表文件。
• 5.5 三个"桶"三种语义。Iceberg 的桶是分区、Paimon 的桶是正确性约束、Hive 的桶才是 shuffle 优化；SPJ 让湖表有了理论上的可能，但那是实测项。
• 5.6 四层漏斗收口成一张填数表。本章的结论必须由读者的实测数字来补完——这不是留白，这是这一章真正教的东西：优化器的能力上限是物理布局给的，而布局的效果只有量过才知道。

下章预告：布局能裁掉数据，但前提是类型选对——第 6 章《数据类型、VARIANT 与 ANSI 语义》。Spark 4 起 spark.sql.ansi.enabled 默认 true 带来的行为清单，除零/溢出/字符串转数值失败从"静默给 NULL"变成"抛异常"；Timestamp / TimestampNTZ / Date 的时区语义（回扣前作"Doris DATETIME 不得带毫秒"与"Doris 4.1 Arrow DATE 有时区问题"）；collect_time 13 位毫秒要除 1000 这个坑在 Spark 侧的对应写法；以及 4.1 GA 的 VARIANT——车端那种"字段数量和内容都不定的信号包"，展开成宽表、存 String 加 JSON 函数、存 VARIANT，三种方案的存储与查询代价差多少。

官方参考资料

版本取证说明

本章取证日期：2026-11-03。抓取路径说明：https://spark.apache.org/docs/latest/* 当前渲染为 4.3.0 文档，因此涉及 Spark 侧的每一条都另行比对了 4.1.4 同名页面；Iceberg 按 docs/latest（面包屑标注 Latest = 1.12.0）与仓库 docs/docs/*.md 源文件取证；Paimon 官方站点为客户端渲染、抓取不稳定，逐字原文取自 Apache Paimon 仓库 master 分支文档源，1.4.2 的措辞未逐字验证，凡引用处均标注为 master。

实操清单

前置：第 2 章环境（4.1.4 主线，Paimon 相关步骤如遇不兼容改在 4.0.5 跑）、paimon.demo.ods_vehicle_telemetry 20 万行、iceberg.demo.dws_vehicle_daily 与 iceberg.demo.dim_vehicle_info、事件日志已开。本章新建 iceberg.demo.dwd_vehicle_telemetry 与四张 t_layout_*。

第 6、12、13、15 项是本章核心。 第 13 项证明的是本章最容易被忽略的一条因果（排序不回溯历史），第 15 项决定你后面所有湖表 join 的设计前提——这两项没做过，本章的其他内容都只是读过的道理。

思考题

读完这一章，你应该已经能把"这张表慢"翻译成一句具体得多的话：它的 WHERE 条件在哪一层落空了。下一章不再谈位置，谈内容本身——类型选错，存储、压缩、裁剪、正确性四头一起赔。