Apache Beam Parquet I/O 连接器实战指南:基于 ParquetIO 的读写、Schema 推断与 Spark 兼容配置

原创2026-10-09 12:59:282,295 阅读
文章标签:大数据批处理流处理数据工程数据集成

Apache Beam Parquet I/O 连接器实战指南:基于 ParquetIO 的读写、Schema 推断与 Spark 兼容配置

Apache Beam 官方 SDK 内置了针对 Apache Parquet 为骨架,结合当前仓库的源码实现,系统讲解 Parquet I/O 的依赖引入、核心读写 API、投影读取与 Beam Schema 推断等进阶能力,并重点解决 Java 环境下与旧版 Spark 集群混部时 Parquet 依赖冲突的经典问题。读完本文,你将能够独立完成 Beam 管道的 Parquet 数据接入与导出,并掌握跨引擎部署时依赖隔离的完整解决方案。

连接器概览:Beam 中的 Parquet 读写能力

Beam SDK 提供的内置 I/O transform 支持从 Parquet 文件读取数据、向 Parquet 文件写入数据。Java 端连接器的全部能力集中在 ParquetIO.java 一个类中,Python 端则在 parquetio.py 模块内实现。两个 SDK 的读取结果形态不同:

  • Java:读出的 PCollection 元素是 Avro GenericRecord(也可通过解析函数转换为自定义类型);
  • Python:默认读出的是 Python dict(每行一个字典,键为列名),复杂类型如 list 映射为 Python list,struct 映射为 Python dict;底层文件操作由 pyarrow 完成。

两个实现都遵循统一的 Beam I/O 抽象:Java 侧基于 FileIO 构建(因此天然支持 hdfs 等任意文件系统),Python 侧基于 filebasedsource / filebasedsink 构建。

开始之前:依赖引入与运行环境准备

Java:添加 Maven 依赖

在 pom.xml 中引入官方 Maven 构件:

<dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-io-parquet</artifactId>
    <version>{{< param release_latest >}}</version>
</dependency>

在 Gradle 工程中对应为 implementation "org.apache.beam:beam-sdks-java-io-parquet:版本号"。该构件在仓库中的源码路径为 sdks/java/io/parquet,内部依赖 Apache Parquet 与 Apache Avro 的列式读写能力。

Python:随 SDK 预装

Python 侧不需要单独安装 Beam 连接器——parquetio 随 Apache Beam Python SDK 预装。但注意:底层实际执行文件读写的是 pyarrow,因此使用前必须确保环境中安装了可用的 pyarrow。从 parquetio.py 的源码可以看到,模块在导入时会尝试 import pyarrow as pa 与 import pyarrow.parquet as pq,若缺失则以 None 兜底,此时相关 transform 不可用。可以通过 pip install pyarrow 补齐。

Java 端 ParquetIO:从读取到写入的完整 API

基础读取:ParquetIO.read()

ParquetIO.read(Schema) 接收一个 Avro Schema,返回 PCollection<GenericRecord>:

PCollection<GenericRecord> records = pipeline.apply(
    ParquetIO.read(SCHEMA).from("/foo/bar"));

.from(...) 接受单个文件路径或 glob 文件模式(支持 ValueProvider<String> 形式以便运行时参数化)。从源码 ParquetIO.java#L368-L388 可以看到,read 的内部实现依次是:Create 创建文件模式 → FileIO.matchAll() 匹配文件 → FileIO.readMatches() 读取匹配结果 → 交给 ReadFiles 执行真正的逐文件解析。因为基于 FileIO,这一链路天然支持 hdfs、GCS 等任意 Beam 文件系统。

基于文件集合的读取:ParquetIO.readFiles()

当文件列表来自一个 PCollection<FileIO.ReadableFile> 时(例如先经过 FileIO.match().filepattern(...) 与 FileIO.readMatches() 匹配筛选),使用 readFiles 更加灵活:

PCollection<FileIO.ReadableFile> files = pipeline
    .apply(FileIO.match().filepattern(options.getInputFilepattern()))
    .apply(FileIO.readMatches());

PCollection<GenericRecord> output = files.apply(ParquetIO.readFiles(SCHEMA));

可切分读取(Splittable DoFn)

ParquetIO 的读取基于 Splittable DoFn 实现,SplitReadFn(源码见 ParquetIO.java#L711-L943)以行组(Row Group)粒度做切分:初始把文件按 SPLIT_LIMIT = 64000000(64MB)切成多个 OffsetRange 块,随后通过 @SplitRestriction 支持动态再切分,以实现更高的并行读取效率。读取时逐行组读入内存并逐行产出记录,单条损坏记录会被 LOG.warn 记录并跳过,不会中断整个管道。

未知 Schema 读取:parseGenericRecords()

当文件的 schema 在管道构建时未知、或不同文件 schema 不一致时,使用 ParquetIO.parseGenericRecords(parseFn):提供一个 SerializableFunction<GenericRecord, T> 把每条 GenericRecord 转换为你自定义的类型(可通过 record.getSchema() 访问记录自身的 schema)。对应地,parseFilesGenericRecords(parseFn) 用于从 PCollection<ReadableFile> 输入。若无法从 parseFn 推断输出 Coder,需显式调用 .withCoder(...)(源码逻辑见 ParquetIO.java#L580-L598)。

投影读取:withProjection()

只读取部分列可以显著降低 I/O 与解码开销。withProjection(projectionSchema, encoderSchema) 接受两个 Avro Schema:projectionSchema 只包含需要读取的列;encoderSchema 是输出编码时使用的 schema(把不需要的列改为 nullable)。从源码注释(ParquetIO.java#L138-L154)可以了解到其原理与收益边界:

PCollection<GenericRecord> records = pipeline
    .apply(ParquetIO.read(SCHEMA)
        .from("/foo/bar")
        .withProjection(Projection_schema, Encoder_Schema));

注意:投影提升的是读取不需要的列所花费的时间,但 reader 仍会按照编码 schema 遍历数据(同一行内各列数据是交错存储的),因此收益不会严格正比于请求数据量的比例。

推断 Beam Schema:withBeamSchemas()

如果希望后续对 Parquet 数据执行 SQL 或基于 Schema 的 transform(如 Select、GroupBy),必须让读取 transform 推断 Beam Schema 并自动装配对应 Coder:

PCollection<GenericRecord> parquetRecords =
    p.apply(ParquetIO.read(...).from(...).withBeamSchemas(true));

对 readFiles 同样可用:.apply(ParquetIO.readFiles(...).withBeamSchemas(true))。从 getCollectionCoder()(ParquetIO.java#L705-L709)可以看到,开启后使用 AvroUtils.schemaCoder 生成 SchemaCoder,否则回退到普通 AvroCoder。

其他读取配置

  • .withAvroDataModel(GenericData):为 AvroParquetReader 指定数据模型,对通过反射生成的 schema 场景(如 SpecificData)很有用;
  • .withConfiguration(Configuration | Map<String,String>):为底层 ParquetReader 传入 Hadoop 配置,配置项会写入 DisplayData(仅展示 parquet 前缀的键,见 ParquetIO.java#L402-L409),便于排查问题。

写入:ParquetIO.sink()

Java 侧写 Parquet 需要配合通用 FileIO.write / FileIO.writeDynamic 使用,ParquetIO.sink(Schema) 生成一个 FileIO.Sink<GenericRecord>:

pipeline
    .apply(...) // PCollection<GenericRecord>
    .apply(FileIO
        .<GenericRecord>write()
        .via(ParquetIO.sink(SCHEMA)
            .withCompressionCodec(CompressionCodecName.SNAPPY))
        .to("destination/path")
        .withSuffix(".parquet"));

Sink 的默认配置可以从工厂方法源码(ParquetIO.java#L1005-L1014)确认:

配置项 默认值 说明
CompressionCodecName SNAPPY 输出文件默认压缩编码,可用 .withCompressionCodec(...) 覆盖,如 GZIP、UNCOMPRESSED 等
Row Group 大小 ParquetWriter.DEFAULT_BLOCK_SIZE 行组目标大小,影响写入与后续读取粒度
Page 大小 ParquetWriter.DEFAULT_PAGE_SIZE 列页大小
Dictionary 编码 ParquetWriter.DEFAULT_IS_DICTIONARY_ENABLED 是否启用字典编码
Bloom Filter ParquetProperties.DEFAULT_BLOOM_FILTER_ENABLED 是否启用布隆过滤器
写模式 OVERWRITE 内部使用 withWriteMode(OVERWRITE) 打开写文件(见 ParquetIO.java#L1192-L1196)

Python 端 parquetio:ReadFromParquet 与 WriteToParquet

读取:ReadFromParquet

with beam.Pipeline() as p:
    records = p | 'Read' >> beam.io.ReadFromParquet('/mypath/mypqfiles*')

核心参数(源码定义见 parquetio.py#L254-L309):

  • file_pattern:要读取的 glob 文件模式;
  • min_bundle_size:切分 bundle 时考虑的最小字节数;
  • validate:管道创建时是否校验文件存在;
  • columns:只读取指定列,列名可以是嵌套字段前缀,例如 'a' 会选中 a.b、a.c、a.d.e;
  • as_rows:若为 True,输出带 Schema 的 Beam Row PCollection 而非 Python dict;此时若指定了 columns,schema 会被过滤为这些顶层列(实现见 parquetio.py#L317-L330)。

与 Java 端"按行组切分"的原理一致,Python 端的 _ParquetSource.read_records(parquetio.py#L438-L480)同样以行组为分裂粒度:通过 RangeTracker 定位起始行组(优先取字典页偏移,无字典页则取数据页偏移),逐个行组读取并产出 pyarrow.Table。

相关变体:

  • ReadAllFromParquet:从 PCollection 中的文件名/文件模式批量读取,支持 min_bundle_size、desired_bundle_size(默认 64MB)、columns、with_filename(输出 KV,键为文件名);
  • ReadFromParquetBatched / ReadAllFromParquetBatched(实验性):以 pyarrow.Table 形式产出每行组数据,便于直接 table.to_pandas() 转 DataFrame 处理。

写入:WriteToParquet

with beam.Pipeline() as p:
    records = p | 'Read' >> beam.Create(
        [{'name': 'foo', 'age': 10}, {'name': 'bar', 'age': 20}]
    )
    _ = records | 'Write' >> beam.io.WriteToParquet(
        filename,
        pyarrow.schema([('name', pyarrow.binary()), ('age', pyarrow.int64())])
    )

核心参数(源码定义见 parquetio.py#L485-L589):

参数 默认值 说明
file_path_prefix 必填 输出路径前缀,实际文件名为"前缀 + 分片标识 + 后缀"
schema 可选 pyarrow.Schema 类型;若为 None 且输入是带 Schema 的 Beam PCollection,会从元素类型自动推导
row_group_buffer_size 64 * 1024 * 1024(64MB) 行组缓冲字节数(内存中未压缩数据的尺寸,通常远大于落盘行组大小)
record_batch_size 1000 每个 record batch 的记录数;想按记录数控制行组大小时,可把 row_group_buffer_size 设为 1 并用此参数调节
codec 'none' 块级压缩编码,接受 pyarrow 支持的任意字符串(如 'snappy'、'gzip')
use_deprecated_int96_timestamps False 是否将纳秒精度时间戳写入旧版 INT96 格式
use_compliant_nested_type False 是否写出符合规范的 Parquet 嵌套类型(list)
file_name_suffix '' 输出文件后缀,如 .parquet
num_shards 0 输出分片数;不设置时由服务决定最优分片,人为约束会降低管道性能,非必要不建议设置
shard_name_template 见说明 分片命名模板,支持 ''、'-SSSSS-of-NNNNN'、'-W-SSSSS-of-NNNNN'(窗口分片)与 '-V-SSSSS-of-NNNNN';有界输入默认 '-SSSSS-of-NNNNN',无界输入自动切换为带 W 的窗口模板(见 parquetio.py#L609-L617)
mime_type 'application/x-parquet' 文件 MIME 类型(文件系统支持时生效)
triggering_frequency None 无界输入时每隔该时长触发窗口写出,会覆盖用户窗口设置;GlobalWindow 下为必填

写入路径的内部流程(parquetio.py#L619-L635):有界输入先经 _RowDictionariesToArrowTable(或 _BeamRowsToArrowTable)把 dict/Row 攒成 pyarrow.Table,再交给 Write sink 落盘;无界输入则把转换函数挂到 sink 上直接写出,并在 finish_bundle 时按窗口边界输出(带时间戳与窗口信息,见 parquetio.py#L132-L147)。WriteToParquetBatched(实验性)则直接消费 PCollection 中的 pyarrow.Table 批量写出。

特别场景:ParquetIO 与 Spark 2.4 之前的兼容性处理

问题根源

ParquetIO 依赖 Apache Parquet 1.10.0 引入的 API。Spark 2.4.x 本身兼容,无需额外处理;但更老版本的 Spark 集群上预装的 Parquet 库优先级更高,会在执行期抢先加载,导致 Beam 管道使用的较新 Parquet API 找不到而失败。需要说明的是,以下方案只是让管道在旧集群上正确执行,Beam 连接器读写生成的 Parquet 文件仍应与集群上其他工具保持互操作。

解决方案:maven-shade-plugin 依赖重定位

首先正常引入 Parquet 构件,确保其传递依赖把正确版本的 Parquet 带入:

<dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-io-parquet</artifactId>
    <version>${beam.version}</version>
</dependency>

然后配置 maven-shade-plugin 在打包阶段重定位相关包:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <configuration>
    <createDependencyReducedPom>false</createDependencyReducedPom>
    <filters>
      <filter>
        <artifact>*:*</artifact>
        <excludes>
          <exclude>META-INF/*.SF</exclude>
          <exclude>META-INF/*.DSA</exclude>
          <exclude>META-INF/*.RSA</exclude>
        </excludes>
      </filter>
    </filters>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <shadedArtifactAttached>true</shadedArtifactAttached>
        <shadedClassifierName>shaded</shadedClassifierName>
        <relocations>
          <relocation>
            <pattern>org.apache.parquet</pattern>
            <shadedPattern>shaded.org.apache.parquet</shadedPattern>
          </relocation>
          <!-- Some packages are shaded already, and on the original spark classpath. Shade them more. -->
          <relocation>
            <pattern>shaded.parquet</pattern>
            <shadedPattern>reshaded.parquet</shadedPattern>
          </relocation>
          <relocation>
            <pattern>org.apache.avro</pattern>
            <shadedPattern>shaded.org.apache.avro</shadedPattern>
          </relocation>
        </relocations>
        <transformers>
          <transformer
            implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

配置要点说明:

  • META-INF/*.SF、*.DSA、*.RSA 排除项:避免合并 jar 时签名文件冲突导致的 SecurityException;
  • org.apache.parquet → shaded.org.apache.parquet:把 Beam 依赖的 Parquet 移入 shaded. 命名空间,避免与 Spark classpath 上的旧版 Parquet 冲突;
  • shaded.parquet → reshaded.parquet:部分旧 Spark 发行版已经自带 shaded.parquet 前缀的包,需要再重定位一层防止二次冲突;
  • org.apache.avro → shaded.org.apache.avro:Avro 同样可能被 Spark 预装,一并隔离;
  • ServicesResourceTransformer:合并 META-INF/services 下的服务注册文件,保证 ServiceLoader 机制在 shaded jar 中正常工作。

该方案已在 Spark 2.2.3、Spark 2.3.3 与 Spark 2.4.3 上验证可用(Spark 2.4+ 为可选项)。

小结:如何选择与验证 Parquet I/O 方案

  • Java 管道:引入 beam-sdks-java-io-parquet,读用 ParquetIO.read / readFiles(可选投影、Beam Schema 推断、自定义 parseFn),写用 FileIO.write + ParquetIO.sink;默认 Snappy 压缩;
  • Python 管道:ReadFromParquet / WriteToParquet 开箱即用(需 pyarrow),行组粒度切分与 Java 端对齐;批处理场景可选用 Batched 变体;
  • 部署兼容性:目标集群若运行 Spark 2.4 之前版本,用 maven-shade-plugin 重定位 Parquet 与 Avro 依赖,规避类加载冲突;
  • 验证手段:仓库内提供了完整测试与集成测试可参考——单元测试见 ParquetIOTest.java,端到端集成测试见 ParquetIOIT.java,Python 侧行为可由 parquetio.py 的 docstring 测试用例验证。实际使用中,建议在本地 DirectRunner 上先用小数据集跑通读写闭环,再迁移到目标 Runner 与集群环境。
登录后查看全文
beam