Apache Beam 2.35.0 版本深度解析:MultiMap Side Inputs、ParquetIO 可拆分读取与 I/O 生态升级

原创2026-10-08 23:00:381,729 阅读
文章标签:大数据批处理流处理数据工程数据集成

Apache Beam 2.35.0 版本深度解析:MultiMap Side Inputs、ParquetIO 可拆分读取与 I/O 生态升级

Apache Beam 2.35.0 于 2021 年 12 月 29 日发布,是 Beam 在统一批流编程模型上持续演进的重要版本。本篇文章围绕该版本官方发布说明展开,逐项剖析 Go SDK MultiMap Side Inputs、Dataflow Runner 对 Splittable DoFn 内 Side Input 的支持、ParquetIO 可拆分读取默认开启等核心变更,并结合当前仓库源码(JdbcIO.java、textio.py、ParquetIO.java 等)深入讲解其底层实现与迁移要点,帮助你评估升级影响并平滑完成版本切换。

版本概览

Apache Beam 2.35.0 在 I/O、SDK 能力与运行时安全三个方面同时发力:

  • Go SDK 迎来两项里程碑能力:MultiMap Side Inputs 正式支持(BEAM-3293),以及跨 Bundle 的 Side Input 缓存(通过 EnableSideInputCache hook 开启,BEAM-11097);
  • Java SDK(Dataflow Runner) 首次在 Splittable DoFn(SDF)内支持 Side Inputs,覆盖 Runner V1 与 Runner V2(BEAM-12522);
  • 安全性 方面,测试套件中的 Log4j 版本升级至 2.17.0,以规避 CVE-2021-44228(Log4Shell)影响(BEAM-13434)。

与此同时,Python 与 Java 的多个 I/O 连接器完成了易用性与性能改进,包括 Python TextIO 自定义分隔符、ParquetIO 默认开启可拆分读取、JdbcIO 分区列类型调整等,这些变更中既包含新增特性,也包含需要升级时留意的破坏性变更。

Highlights:本版本的三大核心亮点

1. Go SDK 支持 MultiMap Side Inputs

MultiMap(多值映射)Side Input 允许主输入按 Key 关联到一组值(而非单一值),这对于实现"每个主元素查询一张键到列表的查找表"这类场景非常关键。2.35.0 之前该能力在 Go SDK 中长期缺失,本版本补齐后,Go 用户可以直接以多值映射方式注入 Side Input。

从当前仓库源码看,Go SDK 已经完整落地了这一能力:函数签名解析层在 fn.go 中新增 FnMultiMap 标记,用于识别接收 MultiMap 类型的函数入参;Side Input 合法性校验在 sideinput.go 中完成,其错误信息明确要求"多值映射的输出必须是合法的迭代类型"(errIllegalParametersInMultiMap)。运行执行层(data.go)也提供了 OpenMultiMapSideInput 接口,负责按 Key 打开字节流读取多值映射数据。这三个层级(函数解析、图构建、运行时执行)的协同实现,印证了 MultiMap Side Input 从 API 到执行引擎的完整链路。

2. Dataflow Runner 在 Splittable DoFn 内支持 Side Inputs

Splittable DoFn(SDF)是 Beam 实现"按元素细粒度拆分、动态并行"的核心机制。2.35.0 之前,SDF 的 ProcessElement 中不能直接访问 Side Inputs,导致许多依赖外部查找数据的可拆分处理无法实现。本版本在 Dataflow Runner V1 与 V2 中解除了这一限制(BEAM-12522),使 SDF 用户可以在处理每个元素的分片(restriction)时读取查找数据,显著扩展了可拆分读取的适用面。

3. Log4j 安全升级与 CVE-2021-44228 说明

针对 2021 年底爆发的 Log4Shell 漏洞(CVE-2021-44228),Beam 团队将测试套件使用的 Log4j 升级至 2.17.0(BEAM-13434)。需要特别说明的是:

  • Beam 自身的运行时并不依赖受影响的 log4j-core 依赖,因此 Beam 核心管线不受该 CVE 直接影响;
  • 但如果你的构建配置中(直接或间接)引入了 Log4j 2 依赖,官方强烈建议将其升级到最新修复版本,并重新部署受影响的管线,以消除潜在风险。

对于使用 HCatalog 相关模块的用户,还需留意本文后续"已知问题"一节中关于传递依赖的专项说明。

I/O 更新详解

JdbcIO.readWithPartitions:分区列类型从 int 改为 long

JdbcIO.readWithPartitions 是 Java JDBC I/O 中面向大表的分区读取 Transform,它按分区列把数据拆成多个范围查询并行执行。2.35.0 将分区的范围数据类型从 int 改为 long(BEAM-13149),这是一次"相对较小的破坏性变更",目的是在不累积技术债的前提下提升易用性——毕竟 int 只能表达约 21 亿以内的分区边界,对于大数据量场景容易溢出。

在 JdbcIO.java 中可以看到该变更的最终形态:无参工厂方法 readWithPartitions() 的返回类型已收敛为 ReadWithPartitions<T, Long>,内部默认使用 TypeDescriptors.longs();而 readWithPartitions(TypeDescriptor<PartitionColumnT>) 仍保留给非 long 分区列(如字符串列)的高级用法。使用该 Transform 时需要通过 withPartitionColumn 指定分区列,并通过 withLowerBound/withUpperBound 设定分区范围、withNumPartitions 设定分区数;也支持使用子查询作为表名(如 "(select id, name from Person) as subq"),并可用 withRowMapper 自定义行映射。仓库测试 JdbcIOTest.java 与集成测试 JdbcIOAutoPartitioningIT.java 对该 API 的行为进行了系统验证。

升级注意:官方明确表示该 Transform 相对较新,未来可能继续实施其他破坏性变更以改善可用性,升级时请关注发布说明。

ParquetIO:可拆分读取默认启用

ParquetIO 在本版本中默认启用可拆分读取(splittable reading)(BEAM-12070 的源码注释可以看到其实现机制:

ParquetIO leverages splittable reading by using Splittable DoFn. It initially splits the files into the blocks of 64MB and may dynamically split further for higher read efficiency.

即:ParquetIO 通过 Splittable DoFn 实现可拆分读取,初始按 64MB 块切分文件,并在执行过程中进一步动态拆分以提升读取效率。这一能力同时适用于 ParquetIO.read(SCHEMA).from(...) 与 ParquetIO.readFiles(SCHEMA)(配合 FileIO.match/readMatches 使用),并且与投影读取(withProjection,只读取指定列、输出 schema 中其余列置为 nullable)天然兼容——投影读取时 Splittable 同样生效,可减少读取时间与内存占用。与此同时,非可拆分读取被标记为弃用(Deprecation),新代码应直接使用默认的可拆分读取路径。

Python SDK 新特性

TextIO 读取支持自定义分隔符与转义字符

Python 的 ReadFromText 长期以来只支持以换行符(\n)分隔记录。2.35.0 新增了两个参数(BEAM-12730 与 BEAM-13189):

  • delimiter:自定义记录分隔符(bytes 类型)。要求不得自重叠(self-overlap),否则会导致读取错位;
  • escapechar:单个字节的转义字符,用于转义记录中的分隔符,也可以转义自身。

在 textio.py 的实现中可以看到完整的参数校验逻辑:delimiter 必须是非空 bytes 且不能自重叠;escapechar 必须是长度为 1 的 bytes。底层读取逻辑则据此定制记录边界识别:未指定分隔符时默认按 \n(同时兼容 \r\n)切分;指定 escapechar 后,读取器会跳过被转义的分隔符,甚至在定位下一条记录起始位置时,会先回退扫描到第一个 escapechar 再做判断,从而保证转义语义在跨块(chunk)边界依然正确。

# 自定义分隔符与转义字符读取示例(2.35.0 新增能力)
records = (
    p
    | 'Read' >> beam.io.ReadFromText(
        'gs://my-bucket/data.txt',
        delimiter=b'|',       # 以 | 作为记录分隔符
        escapechar=b'\\')     # 用反斜杠转义记录内的 | 字符
)

注意:ReadFromText 的底层 _TextSource 是 FileBasedSource 的可拆分实现(见 filebasedsource.py),自定义分隔符与可拆分读取的组合实现正是本版本的难点与亮点之一——跨块扫描逻辑需要结合分隔符长度与转义字符做精确的起始位置推算。

AvroIO:移除 avro-python3 依赖,统一使用 fastavro

2.35.0 移除了 avro-python3 依赖,fastavro 成为 Python 3 上唯一的 Avro 实现(BEAM-13016 可以看到,模块直接 import fastavro,并使用 fastavro.read.block_reader 与 fastavro.write.Writer 完成读写。

为了保持 API 兼容,ReadFromAvro 与 WriteToAvro 的 use_fastavro 布尔参数被保留但不再产生任何效果(源码注释明确标注"left for API backwards compatibility")。升级后:

  • 旧的 use_fastavro=False 调用不再有意义,代码无需改动即可运行,但该参数实际已被忽略;
  • 建议后续在代码中移除该参数,避免误导阅读者。

远程包支持从 Beam Filesystems 下载

本版本允许远程依赖包从 apache_beam.io.filesystems 支持的任何位置下载(BEAM-11275)。Stager 会先下载这些文件,再上传到 Staging 位置。这意味着你可以把自定义依赖放到 GCS、S3 等 Beam Filesystems 可访问的位置,由 Stager 统一处理,而不是仅局限于本地文件或传统 HTTP 下载,为分布式环境下的依赖分发提供了更大灵活性。

Go SDK 新特性

DoFn Execution Time 指标

2.35.0 为 Go SDK 新增了 DoFn 执行时间(Execution Time)指标(BEAM-13001),让 Go 用户可以观测 DoFn 实际执行耗时,为性能剖析与调优提供数据支撑。这补齐了 Go SDK 在运行时指标观测上与 Java/Python SDK 的能力差距。

跨 Bundle 的 Side Input 缓存

对于支持该特性的 Runner,Go SDK 新增了跨 Bundle 的 Side Input 缓存(BEAM-11097)已具备按 StreamID + sideInputID 打开 Side Input 字节流的底层接口,为缓存机制的实现提供了基础。

Bug 修复:Side Input 窗口映射默认行为

同步修复了主输入窗口到 Side Input 窗口的映射问题(BEAM-11087):此前某些场景下主输入窗口未能正确映射到对应的 Side Input 窗口,现在默认行为已修正,窗口化场景下 Side Input 的取值将符合语义预期。

破坏性变更(Breaking Changes)与迁移指南

1. 跨语言 Transform 的 URN 约定更新

2.35.0 为跨语言(cross-language)Transform 采用了新的 URN 命名约定,并更新了既有 URN(BEAM-12047)。URN(Uniform Resource Name)是跨语言 Transform 在 Expansion Service 之间标识与路由的核心标识符,此变更会影响高级使用场景——例如用自定义 Expansion Service 连接不同版本的 Beam Java 与 Python SDK 时,新旧 URN 不匹配可能导致无法解析。升级建议:

  • 尽量让参与跨语言调用的 Java 与 Python SDK 保持同版本;
  • 若使用自定义 Expansion Service,请同步升级并验证 URN 兼容性。

2. Calcite 1.28.0 升级:SUBSTRING 函数语义变更

SqlTransform 升级到 Calcite 1.28.0(BEAM-13099),其中 Calcite 方言下 SUBSTRING 函数存在破坏性变更(关联 CALCITE-4427)。如果你在 SqlTransform 中使用了 SUBSTRING,需要根据 Calcite 方言的新语义核对 SQL 结果,尤其是参数边界与空值行为。

3. Kinesis I/O:ListShards 替代 DescribeStream

Kinesis 连接器(AWS SDK v2)改用 ListShards(配合 DescribeStreamSummary)来枚举分片,替代此前的 DescribeStream(BEAM-13233)。这一变更是对精细粒度(fine-grained)IAM 策略的破坏性变更:如果你为 Kinesis 配置了最小权限策略,必须新增对 ListShards 与 DescribeStreamSummary 两个 API 的调用权限,否则分片枚举将失败并导致读取异常。

已知问题与升级注意事项

  • HCatalog 用户的 Log4j 传递依赖(BEAM-13499):使用 beam-sdks-java-io-hcatalog(或 beam-sdks-java-extensions-sql-hcatalog)的用户,在添加 Hive 依赖时必须主动覆盖传递进来的 log4j 依赖版本,否则可能引入存在已知漏洞或行为差异的旧版本 Log4j。建议在构建配置中显式锁定 Log4j 2 的最新安全版本。

其他 Bug 修复汇总

  • Java / DynamoDB 写入数据丢失修复(BEAM-13009):未设置去重键名(deduplication key names)时写入 DynamoDB 可能发生数据丢失,本版本修复;
  • Python / WriteToFiles 流式管线数据丢失修复(BEAM-12950):在流式(streaming)管线中使用 WriteToFiles 时的数据丢失问题已修复;
  • Go SDK 示例注册修复(BEAM-5378):Go SDK 的示例程序现已注册类型与函数,确保序列化/注册机制在示例中正常工作。

结语:升级路径建议

综合来看,Apache Beam 2.35.0 是一个"能力扩展 + 安全加固"并重的版本。升级前建议按以下清单自查:

  1. 检查 JdbcIO.readWithPartitions 的使用:确认分区列范围是否超出 int 上限,按 long 语义调整边界参数;
  2. 检查 Kinesis IAM 策略:为 ListShards 与 DescribeStreamSummary 授权;
  3. 检查跨语言 Transform 的 URN 使用:确认自定义 Expansion Service 两侧 SDK 版本对齐;
  4. 检查 SqlTransform 中的 SUBSTRING:按 Calcite 1.28.0 语义核对结果;
  5. 升级 Log4j 2 依赖:无论是否直接使用,排查传递依赖并锁定安全版本;
  6. 验证 Python TextIO/AvroIO 行为:确认新分隔符/转义字符参数符合预期,use_fastavro 参数虽已无效但仍兼容。

对于 Go SDK 用户,MultiMap Side Inputs、跨 Bundle Side Input 缓存与 DoFn 执行时间指标是值得优先尝试的新能力;Java 用户则可重点关注 Splittable DoFn 内 Side Inputs 带来的 SDF 编程范式扩展。若希望对比相邻版本的变化脉络,可继续阅读仓库中同系列发布说明(如 beam-2.34.0.md 与 beam-2.36.0.md),并结合上述源码路径深入验证各变更的底层实现。

登录后查看全文
beam