Apache Beam Parquet I/O 连接器实战指南:基于 ParquetIO 的读写、Schema 推断与 Spark 兼容配置
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元素是 AvroGenericRecord(也可通过解析函数转换为自定义类型); - Python:默认读出的是 Python
dict(每行一个字典,键为列名),复杂类型如 list 映射为 Pythonlist,struct 映射为 Pythondict;底层文件操作由 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 与集群环境。