Apache Iceberg Variant 与 Shredding：机制、上游进展与实测归因

0. 结论速览

1. 设计初衷与目标

先把「Variant 到底为什么存在」讲清楚，后面所有性能讨论都建立在这个基础上。

1.1 解决的是「JSON 字符串重复解析」这个老问题

Variant 不是为某个新潮场景发明的。各社区的原始 proposal 用几乎一致的语言描述动机：

• Spark SPIP（SPARK-45891）：用户依赖 JSON 表达式处理 JSON 数据，"can often lead to repeated JSON parsing and degraded performance"；目标是 "use a more efficient binary representation internally and avoid repeated JSON parsing"，同时 "keeps the flexibility of schemaless JSON data"。
• Iceberg Variant Proposal（Issue #10392）：通过编码为 variant 列，"we retain the flexibility of the source data, while allowing query engines to more efficiently operate on the data"。
• Databricks 工程博客把取舍说得最直白："Without Variant, customers had to choose between flexibility and performance."

1.2 两层目标，正好对应「存储已兑现 / 查询未兑现」的分界

公开 spec 把目标拆成了两层，这个拆分是理解后文一切的钥匙：

1.3 附带能力：运行时 Schema 自描述

Spark 提供公开内置函数 schema_of_variant / schema_of_variant_agg，可在查询运行时从数据本身推断出 Variant 的结构和类型，无需事先定义或维护 schema。这是 §1.1 中 "schemaless / 保留源数据灵活性" 设计目标的自然结果 —— schema 信息内嵌在数据里、可被运行时读出。

相比之下，JSON String 列对引擎是不透明的：DESCRIBE table 只能看到 payload STRING，任何消费方想知道里面有什么字段都得自己采样猜。这条能力与 shredding 无关，当下即可使用，实测见 §8。

2. 技术机制

2.1 为什么传统两种方案都不行

2.2 物理存储格式

VARIANT 在 Parquet 文件中存储为带两个 binary 字段的 group：

optional group variant_col (Variant(1)) {
  required binary metadata;   -- 类型信息（字段名字典、类型编码）
  required binary value;      -- 实际数据
}

metadata 携带结构信息（字段名到 ID 的映射），value 存储编码后的值。这种自描述设计使每行可以有不同结构，同时支持列级读取。

VARIANT 的类型范围比 JSON 更宽：除 JSON 原生的 string / number / boolean / null / array / object 之外，还原生支持 date、timestamp（含 / 不含时区）、decimal、binary。存为 date 的字段查询时不需要运行期转换，范围过滤直接生效。

2.3 Shredding 做了什么

写入时：引擎分析被写入的 VARIANT 值，将高频出现的字段额外提取为独立的 typed Parquet 列（typed_value）。主 VARIANT 二进制列完整保留 —— 无信息丢失、不施加 schema 约束，shredded 列是额外的「快速通道」。

读取时（理论上）：查询访问被 shredded 的字段时直接读 typed 列，跳过二进制解码；谓词可下推到 typed 列，实现 row group / page 级跳过。

2.4 Manifest 中的 shredded subcolumn 统计（V3 新增）

为支持 shredded subcolumn 的 file pruning，V3 扩展了 manifest 中 VARIANT 列的 bounds 编码方式：

对现有 manifest 格式完全兼容（value 仍是 binary）。Bounds 收集条件：该文件内 subcolumn 所有值类型一致才收集；混合类型或全 null 不收集。value_counts / null_value_counts 等统计推迟到 Iceberg format V4。

2.5 读写函数

3. 四层性能来源辨析（本文核心）

市面上几乎所有 Variant 性能讨论 —— 包括我们自己早期的测试报告 —— 都把下面四件事混为一谈，导致归因错误。它们的实现状态完全不同，必须分开看。

还有一条容易和上面四条混淆的独立线：向量化读取（Arrow VarBinary 批量读 metadata + value）。它已经合并进 Iceberg 1.12.0，但只服务非 shredded 表，对 shredded 表会主动关闭批量读退回逐行。详见 §6.2。

4. 我们的实测数据

三组测试呈现了与工作负载强相关的不同表现。单看任何一组都会得出错误结论，必须合起来读。

4.1 游戏行为日志：42 亿行，Variant 全面落后

环境：4,206,291,624 行 · bucket(8, aid) 分桶 · S3 Tables Iceberg V3 zstd · Spark 4.1.2 + Iceberg 1.11.0 · 1 次 warmup + 3 次正式取均值

存储

查询性能

单函数对照更干净：variant_get(detail, '$.map_id', 'STRING') = 40,120 ms vs get_json_object(detail, '$.map_id') = 27,844 ms。

4.2 COVID 多源数据：2 亿行，Variant 反超

存储侧：2 亿行物理实测节省 16%（15.3 vs 17.7 bytes/row）。此优势与 Catalog 后端无关 —— S3 Tables 与 Glue 趋势一致。

这组数据的重要性在于：它是「机制 ①」的第一个干净样本。大表全表扫描时 CPU 不再被逐行 variant_get 调用主导，二进制编码免解析的优势显现。

4.3 Agent Trace Log：4.11 亿行，Variant 大胜 —— 但原因不是 shredding

环境：411,141,272 行 OTel spans（Kafka Structured Streaming 实时写入）· S3 Tables Iceberg V3 zstd · Spark 4.1.2 on EKS（10 executors × 4 cores, 12 GB）· 分区 days(start_time)

结果

存储：Variant 20.39 GB（381 文件 / 平均 54.80 MB）vs JSON 23.65 GB（76 文件 / 平均 318.60 MB），节省 13.8%（3.26 GB）。

证据 1：配置键在 Spark 中不存在

报告的测试环境写的是：

spark.sql.parquet.variantShreddingEnabled: "true"

核对 Spark master 的 SQLConf.scala，所有 variant 相关配置都在 spark.sql.variant.* 下，没有 spark.sql.parquet.variantShreddingEnabled 这一项：

Spark 对未知的 spark.sql.* 配置静默接受、不报错，所以这一行等于什么都没做，而且不会有任何警告。

证据 2：即使键名写对了，Iceberg 也不看它

spark.sql.variant.* 是 Spark 内置 Parquet data source 的开关，而我们写的是 Iceberg 表。Iceberg 有自己独立的开关：

// Iceberg 1.11.0 core/src/main/java/org/apache/iceberg/TableProperties.java:161
public static final String  PARQUET_SHRED_VARIANTS         = "write.parquet.shred-variants";
public static final boolean PARQUET_SHRED_VARIANTS_DEFAULT = false;   // ← 默认 false

Iceberg 的 Parquet.WriteBuilder.forTable(table) 走的是 setAll(table.properties()) —— 只读表属性，variantShreddingFunc 由此装配。Spark session 里的 spark.sql.variant.* 完全不参与 Iceberg 的写入决策。

默认 false + 报告未设置该表属性 ⇒ 该表极可能是未 shredded 的纯 binary Variant 表。

证据 3：对照组设对了

同期的游戏数据测试报告明确记录了表属性：

Table Properties: [format-version=3, write.parquet.shred-variants=true,
                   write.parquet.compression-codec=zstd]

这也解释了为什么游戏报告能观察到「shredding 后 Parquet 从 3 列增至约 990 列」这类物理证据，而 Agent Trace 报告通篇没有任何 shredded 列数、EXPLAIN 输出或 Parquet schema 的直接证据 —— 所有「Shredding 生效」的表述都是推断，不是观测。

证据 4：报告自身前后矛盾

报告同时声称「列裁剪已生效」和「列裁剪尚未实现」，二者不能同时为真。同一套技术栈在两周前已被 EXPLAIN 证伪，所以正确的一半是「尚未实现」。

那 1.38x~1.90x 到底来自哪里？

来自机制 ① —— Variant 二进制编码免去 JSON 文本解析。有意思的是，报告自己的根因分析其实说对了机制，只是错误地挂在了「Shredding」名下：

• get_json_object() 需线性扫描文本到目标路径 —— 字符串越长、路径越深越慢
• variant_get() 通过 binary offset + metadata 字典直接定位 —— 路径深度不影响
• 4.11 亿行 × 500~2000 字节的累积差异 → Variant 快 1.4x~1.9x

连带修正：Q5 的 0.66x 也归因错了

报告把点查慢归因为「Shredding 后 Parquet 列数更多、I/O 量更大」。若真未 shredded，这解释站不住。更可能是文件布局差异：

Variant 表 381 文件 × 55 MB vs JSON 表 76 文件 × 319 MB。全表扫描找几行时，文件数多 5 倍意味着 5 倍的 footer 读取和任务调度开销。报告自己也注明了「Streaming 触发频率相同但 Spark 合并策略不同」导致文件数差异，却未把它纳入性能归因。

Q4 的 0.50x 绝对值只有 359 ms vs 180 ms，可忽略。

修正后的结论表

4.4 三组结果为何看似矛盾 —— 其实完全一致

关键：三组测试都没有用上 shredding 的列裁剪（connector gap 导致）。所以它们本质上都是在比两个运行时函数：variant_get() vs get_json_object()。谁赢完全取决于工作负载：

当前阶段的 Variant 查询优势 = f(JSON 字符串长度, 字段数, 路径深度, 需解析的行数)
                             —— 与 shredding 无关

5. 配置踩坑：Iceberg 表属性 vs Spark session 配置

正确的启用方式

-- 建表时
CREATE TABLE catalog.db.events (
  event_id BIGINT,
  payload  VARIANT
) USING iceberg
TBLPROPERTIES (
  'format-version'                              = '3',
  'write.parquet.shred-variants'                = 'true',
  'write.parquet.variant-inference-buffer-size' = '100'
);

-- 已有表开启（只影响后续写入的新文件）
ALTER TABLE catalog.db.events
SET TBLPROPERTIES ('write.parquet.shred-variants' = 'true');

配置优先级：DataSource Write Option > Spark Session Config（iceberg 前缀） > Table Property > Default

• Session 级：spark.conf.set("spark.sql.iceberg.shred-variants", "true") — 注意是 iceberg 而非 variant
• Write option 级：df.writeTo("table").option("shred-variants", "true").append()

6. 上游进展追踪（截至 2026-07-29）

6.1 Iceberg 侧：实现已写好，但都还没合并

原先追踪的 issue #16448（"SparkScanBuilder 未实现接口"）现在已有对应实现 PR，作者均为 qlong：

合并顺序：#16714 先 → #16715 后（端到端测试需要两者）。两个 PR 都还差至少一个 approving review。

#16714 自带的基准数据 —— 下推生效后确实翻盘

这是本轮调研最有价值的发现。作者用一天的 GitHub activity 数据（JSON + 299 个 shredded 列）做基准，取 3 次运行中位数：

单查询最极端：c-q08 3.701 s（下推 ON）vs 87.059 s（下推 OFF），差 23 倍。

6.2 另一条线：向量化读取（#16292，已合并，但对 shredded 表无效）

PR #16292 — "Spark: Add vectorized Parquet reads for variant columns"，作者 nssalian：

这与社区 Sync 纪要里「向量化读取器接近就绪，提升非裂解 Variant 读取性能」一条完全对应 —— 注意原文限定词就是「非裂解」。

结论：#16292 是好消息（Variant 基础读取性能改善，且是目前唯一确定进 1.12.0 milestone 的 variant 读取相关改动），但它不解决我们实测到的问题。

关联：#16087（向量化 builder 的 variant 处理修复，其临时补丁被 #16292 移除）；#16913（ColumnVectorWithFilter 子向量修复，Open）。⚠️ 副作用需留意：#16292 让 variant 走上向量化路径并触及 DV / position delete 交互，而 #16913 仍 Open 说明这块 nested/child vector 语义还在收敛。若在 1.12 上跑 Variant + DV 组合，建议留一轮回归验证。

6.3 Spark 侧：4.2 已发布但不含 variant 性能修复

6.4 当前能拿到什么、拿不到什么

作者 qlong 在 #16715 中的表述，是目前最权威的分期判断：

6.5 对既有预期的修订

7. AWS 侧支持矩阵

7.1 各服务 Variant 支持状态

7.2 S3 Tables 公告的正确解读

来源：AWS What's New, 2026-07-28

官方描述的工作机制三条：

1. 任何 Iceberg V3 兼容引擎在写入时将半结构化数据 shred 到 hidden columns
2. Shredding 产生 Parquet column statistics，引擎据此做 file pruning
3. S3 Tables 的自动维护（含 Compaction）覆盖 Variant 列

可用区域（15 个）：US（N. Virginia / Ohio / Oregon）、Asia Pacific（Mumbai / Seoul / Singapore / Sydney / Tokyo）、Canada（Central）、Europe（Frankfurt / Ireland / London / Paris / Stockholm）、South America（São Paulo）。

7.3 Iceberg V3 逐特性支持（AWS）

8. 已兑现的价值：运行时 Schema 自描述

虽然 shredding 查询加速没兑现，但有一块能力完全不依赖 shredding、现在就能拿到。

8.1 核心机制

JSON String 列对引擎是不透明的 —— DESCRIBE table 只能看到 payload STRING，要知道里面有哪些字段只能靠采样。而 Variant 列一次 schema_of_variant_agg() 就能拿到精确字段名与类型，且随数据变化自动更新。

8.2 三个实测验证场景

环境：Phase 1 = 110 万行（100 万正常 + 10 万脏数据），Phase 2 增加 5 万行含新字段。测试方式为不允许探索性 SELECT * LIMIT N、仅凭 Catalog 元信息生成 SQL

COVID 实验进一步验证：一次 schema_of_variant_agg 即可拿到全部 8 种 source 的完整 schema，据此生成的 5 条业务 SQL 全部正确、零失败；而多宽表方案需 6 次 DESCRIBE 并自行判断字段语义是否等价，易出错。

9. 选型建议

10. 待验证事项

10.1 确证 Agent Trace 表的 shredding 状态（按成本从低到高）

1. 查表属性（1 分钟，决定性）：SHOW TBLPROPERTIES tracelog.otel_spans_v2; —— 看 write.parquet.shred-variants 是否 = true；缺失或 false 即未 shredded
2. 查 Parquet 物理 schema（决定性）：读一个数据文件的 footer，看 attributes 下是否只有 metadata + value（未 shredded），还是另有 typed_value 子列（已 shredded）
3. EXPLAIN FORMATTED 跑 Q1/Q3，确认 scan 的 Output 是否仍是完整 attributes 列
4. 真正的 A/B：同一份数据写两张 Variant 表，唯一差别是 write.parquet.shred-variants true/false，重跑 Q1~Q5。这是唯一能隔离出 shredding 净效应的实验 —— 现有报告缺的正是这个对照组

附带价值：若 otel_spans_v2 确实未 shredded，那么升级到 Iceberg 1.12 后这张表能直接吃到 #16292 的向量化收益，而开了 shredding 的游戏日志表反而吃不到。这个反差值得在第 4 步的 A/B 中一并验证。

10.2 其他待验证

• S3 Tables 的 file pruning 是否真实生效 —— 在 S3 Tables 上复测单列查询，确认是否真的少读文件、以及是否已绕过 Variant 重建开销。这决定 AWS 是否用了自有分支
• cherry-pick #16714 + #16715 提前验证 —— 自建 Iceberg 跑我们的游戏日志数据集。#16714 基准显示下推 ON/OFF 差 14.8×，值得在我们自己负载上确认，尤其我们的负载「字段少 + 结构统一」是 Variant 最不利场景，验证价值高
• Variant + DV 组合在 1.12 上的回归 —— #16913 仍 Open，nested/child vector 语义还在收敛

10.3 跟踪信号（按重要性）

1. #16714 拿到 approving review → 最近的里程碑
2. Spark 4.3 发布日期 + SPARK-55817 是否复活 → 决定 file skipping 能否兑现
3. Iceberg 1.12.0 release notes → 预期含 #16292（向量化，非 shredded），不要误读为 shredding 下推已就绪
4. #16913 合并情况 → variant + DV 的 child vector 语义是否收敛

附：资料来源

公开一手资料（设计初衷部分）

上述来源的动机 / 目标文本均已逐条核对。Snowflake 工程博客（Variant in Iceberg）抓取时返回 404，未能核到原文，故未列入。

上游 PR / Ticket

Iceberg： #16714 · #16715 · #16448 · #16726 · #15384 · #15385 · #16133 · #16292 · #16087 · #16913
Spark： SPARK-55617 · SPARK-55817 · PR #54598

本团队实测报告

• · 游戏行为日志 Variant Shredding 性能报告（2026-06-01，42 亿行）
• · Agent Trace Log 性能测试报告（2026-06-15，4.11 亿行 OTel spans）
• · Iceberg V3 Variant 实验报告（COVID 多源数据，2 亿行）
• · Variant Schema 自描述验证（110 万行 + 5 万行 schema 演进）
• · S3 Tables Variant 功能验证（2026-04-21）
• · Apache Iceberg Variant 社区同步纪要（2026-06-04）
• · 独立基准：10M JSON 记录 STRING vs VARIANT 存储对比（279.32 → 191.58 MB，−31.4%）