PyFlink DataStream Formats 完整指南:Avro、CSV、JSON、ORC、Parquet 数据格式的读写实战
PyFlink DataStream Formats 完整指南:Avro、CSV、JSON、ORC、Parquet 数据格式的读写实战
PyFlink 的 pyflink.datastream.formats 模块为 DataStream API 提供了统一的文件与流式数据格式支持,涵盖 Avro、CSV、JSON、ORC、Parquet 五种主流格式的读入、写出与行级序列化/反序列化能力。本文以 flink-python/docs/reference/pyflink.datastream/formats.rst 为骨架,结合 flink-python/pyflink/datastream/formats/ 下各模块的源码实现与测试用例,逐类讲解每个格式类的构造方式、参数默认值、底层调用链与完整可运行示例。读完本文,你将能够熟练使用 PyFlink 从 Avro/CSV/Parquet 文件构建 Source、向 FileSink 批量写出 ORC/Parquet/Avro/CSV 文件,并在 Kafka 等流式管道中用 JSON/CSV 的 Row 序列化与反序列化 Schema 打通上下游。
一、模块总览:formats 目录结构与 Java 桥接
pyflink.datastream.formats 的 API 参考文档按数据格式分为五个子模块,每个子模块对应一个独立的 Python 实现文件,且几乎全部通过 Py4J 桥接到 Flink 的 Java formats 模块:
| 子模块(Python 文件) | 公开类 | 对应的 Java 实现(flink-formats) |
|---|---|---|
| avro.py | AvroSchema、GenericRecordAvroTypeInfo、AvroInputFormat、AvroBulkWriters、AvroRowDeserializationSchema、AvroRowSerializationSchema | flink-avro |
| csv.py | CsvSchema、CsvSchemaBuilder、CsvReaderFormat、CsvBulkWriters、CsvRowDeserializationSchema、CsvRowSerializationSchema | flink-csv |
| json.py | JsonRowDeserializationSchema、JsonRowSerializationSchema | flink-json |
| orc.py | OrcBulkWriters | flink-orc |
| parquet.py | AvroParquetReaders、AvroParquetWriters、ParquetColumnarRowInputFormat、ParquetBulkWriters | flink-parquet |
这些类大多在 Flink 1.16.0 版本中引入(源码中均有 .. versionadded:: 1.16.0 标注)。它们的共同特征是:Python 侧只负责参数封装与类型转换,真正的读写逻辑在 Java 侧执行。例如 avro.py 中的 AvroSchema.parse_string 会通过 get_gateway().jvm.org.apache.flink.avro.shaded.org.apache.avro.Schema.Parser().parse(json_schema) 直接调用 Java 的 Avro Schema Parser;csv.py 中的 CsvSchemaBuilder 则封装了 org.apache.flink.shaded.jackson2.com.fasterxml.jackson.dataformat.csv.CsvSchema.builder()。因此使用本模块时,Python 环境需要能连接到 Java Gateway,且对应 formats 依赖须在 Flink 集群 classpath 中可用。
二、Avro:从文件读取到批量写出与 Row 序列化
Avro 子模块在 avro.py 中提供 6 个类,覆盖三种使用场景:文件读取(AvroInputFormat)、配合 FileSink 的批量写出(AvroBulkWriters)、以及面向消息管道(如 Kafka)的 Row 序列化/反序列化(AvroRowDeserializationSchema / AvroRowSerializationSchema)。
2.1 AvroSchema:解析 Schema 的入口
AvroSchema 是对 Java org.apache.avro.Schema 的包装(avro.py),提供两种静态构造方法:
AvroSchema.parse_string(json_schema: str):将 JSON 形式的 Schema 字符串解析为AvroSchema;AvroSchema.parse_file(file_path: str):从本地 Schema 定义文件解析。
from pyflink.datastream.formats.avro import AvroSchema
JSON_SCHEMA = """
{
"type": "record",
"name": "test",
"fields": [
{ "name": "boolean", "type": "boolean" },
{ "name": "int", "type": "int" },
{ "name": "string", "type": "string" }
]
}
"""
schema = AvroSchema.parse_string(JSON_SCHEMA) # 或 AvroSchema.parse_file('/path/to/schema.json')
从源码看,parse_string 使用的是 Flink 内部 shaded(重定位)过的 Avro 类 org.apache.flink.avro.shaded.org.apache.avro.Schema(avro.py),而 parse_file 则会先构造 java.io.File 再交给 Schema.Parser().parse(j_file)(avro.py)。
2.2 GenericRecordAvroTypeInfo:携带 Schema 的类型信息
GenericRecordAvroTypeInfo(avro.py)是 Avro GenericRecord 的 TypeInformation 包装,构造时传入 AvroSchema,内部实例化 Java 的 org.apache.flink.formats.avro.typeutils.GenericRecordAvroTypeInfo。这里有一个关键限制(源码 docstring 明确说明):该类型信息不能直接作为 StreamExecutionEnvironment.from_collection 的 type_info 使用,需要先给数据流补一个透传的 map 函数来声明输出类型。
2.3 AvroInputFormat:读取 Avro 数据文件
AvroInputFormat(avro.py)提供针对 Avro 文件的 FileInputFormat,构造参数为文件路径与 AvroSchema。它内部创建 Java 的 org.apache.flink.formats.avro.AvroInputFormat,并实现 ResultTypeQueryable,将产出类型声明为 GenericRecordAvroTypeInfo。
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.formats.avro import AvroInputFormat, AvroSchema
env = StreamExecutionEnvironment.get_execution_environment()
schema = AvroSchema.parse_string(JSON_SCHEMA)
ds = env.create_input(AvroInputFormat(FILE_PATH, schema))
测试 test_avro.py 验证了 AvroInputFormat 对基础类型、枚举(enum)、联合类型(union)、数组(array,元素为 record)与 map 五类 Avro Schema 的读取,构造测试文件时使用 GenericData.Record 逐字段 put 数据。
2.4 AvroBulkWriters:配合 FileSink 批量写出
AvroBulkWriters.for_generic_record(schema)(avro.py)返回一个 BulkWriterFactory,底层是 Java 的 org.apache.flink.formats.avro.AvroWriters.forGenericRecord(schema._j_schema)。docstring 给出了完整的写出链路示例,其中有两个必须注意的约束:
- FileSink 的前置算子输出类型必须是
GenericRecordAvroTypeInfo; - 前置算子不能直接是
from_collection,需要加一个透传 map 来声明 Avro 类型信息。
from pyflink.common.typeinfo import Types
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSink
from pyflink.datastream.formats.avro import AvroSchema, GenericRecordAvroTypeInfo, AvroBulkWriters
env = StreamExecutionEnvironment.get_execution_environment()
schema = AvroSchema.parse_string(JSON_SCHEMA)
ds = env.from_collection([{'array': [1, 2]}], type_info=Types.PICKLED_BYTE_ARRAY())
sink = FileSink.for_bulk_format(
OUTPUT_DIR, AvroBulkWriters.for_generic_record(schema)).build()
# 透传 map 声明 Avro 类型信息,这是写出到 Avro 文件所必需的
ds.map(lambda e: e, output_type=GenericRecordAvroTypeInfo(schema)).sink_to(sink)
此外,Python 侧的数据结构需要与 Avro Schema 匹配,并保持与原生 Python 数据结构一致的语义:Avro 的 array 对象行为应像 Python 的 list,Avro 的 map 对象行为应像 Python 的 dict(参见 avro.py 的 docstring)。写入测试 test_avro.py 覆盖了 basic/enum/union/array/map 五类写出场景。
2.5 AvroRow 序列化与反序列化 Schema
AvroRowDeserializationSchema 与 AvroRowSerializationSchema(avro.py)用于在 Avro 字节与 Flink Row 之间互相转换,可作用于 Kafka 等消息管道。二者都支持两种构造方式:
- 传入
record_class:指定具体 Avro record 类,可提升性能(源码注释:“Having the concrete Avro record class might improve performance”); - 传入
avro_schema_string:用 Schema 字符串驱动转换。
两个参数都未提供时会抛出 TypeError(raise TypeError("record_class or avro_schema_string should be specified."))。docstring 还提醒:如果 Avro record 中包含逻辑日期/时间类型,需要额外引入 JodaTime 依赖。
from pyflink.datastream.formats.avro import AvroRowDeserializationSchema, AvroRowSerializationSchema
# 反序列化:Avro bytes -> Row
deserialization_schema = AvroRowDeserializationSchema(avro_schema_string=JSON_SCHEMA)
# 序列化:Row -> Avro bytes
serialization_schema = AvroRowSerializationSchema(avro_schema_string=JSON_SCHEMA)
三、CSV:SchemaBuilder 驱动的读写全家桶
CSV 子模块在 csv.py 中实现,是五个子模块中 API 最丰富的一个:既有面向文件源/汇的 CsvSchema/CsvSchemaBuilder/CsvReaderFormat/CsvBulkWriters,也有面向行级转换的 CsvRowDeserializationSchema/CsvRowSerializationSchema。
3.1 CsvSchema 与 CsvSchemaBuilder:声明列与分隔符
CsvSchema 对应 Java com.fasterxml.jackson.dataformat.csv.CsvSchema(csv.py),通过 CsvSchema.builder() 获得 CsvSchemaBuilder 后逐列声明。Builder 支持的列类型与配置方法及默认值汇总如下(依据 csv.py):
| 方法 | 说明 | 默认值 / 约束 |
|---|---|---|
add_array_column(name, separator=';', element_type=None) |
数组列,元素须为基础类型 | separator 默认 ;,element_type 默认 DataTypes.STRING() |
add_boolean_column(name) |
布尔列 | DataTypes.BOOLEAN() |
add_number_column(name, number_type=None) |
数值列 | number_type 默认 DataTypes.BIGINT() |
add_string_column(name) |
字符串列 | DataTypes.STRING() |
add_columns_from(schema) |
将另一个 CsvSchema 的全部列并入当前 Schema | — |
clear_columns() |
清空所有列 | — |
set_allow_comments(allow=True) |
允许 # 前缀的注释行 |
False |
set_any_property_name(name) |
设置任意属性名 | — |
disable_array_element_separator() |
全局禁用数组元素分隔符(等价空串) | — |
remove_array_element_separator(index) |
禁用指定列的数组元素分隔符 | — |
set_array_element_separator(separator) |
设置全局数组元素分隔符 | ; |
set_column_separator(char) |
设置列分隔符 | ,;char 必须为单字符,否则抛 ValueError |
disable_escape_char() / set_escape_char(char) |
禁用 / 设置转义符 | 默认不转义;char 必须为单字符 |
set_line_separator(separator) |
设置行分隔符 | 写时默认 \n;读时识别 \n、\r、\r\n |
set_null_value(null_value) |
设置 null 字面量 | 默认空序列 |
disable_quote_char() / set_quote_char(char) |
禁用 / 设置引号符 | 默认 ";char 必须为单字符 |
set_skip_first_data_row(skip=True) |
跳过 CSV 第一行数据 | False |
set_strict_headers(strict=True) |
严格表头校验,检查表头列名与 Schema 一致 | False |
set_use_header(use=True) |
是否读取表头 | False |
注意 set_column_separator、set_escape_char、set_quote_char 三个方法在传入非单字符时会显式抛出 ValueError(例如 csv.py)。build() 在最终构造 CsvSchema 时,会把 Python 侧累积的字段列表打包为 DataTypes.ROW(self._fields)(csv.py),这个 Row 类型会随 Schema 一起用于后续的 Java 类型推导。
3.2 CsvReaderFormat:构建 FileSource 读取 CSV
CsvReaderFormat.for_schema(schema)(csv.py)将 CsvSchema 转换为 StreamFormat,内部通过 Java 的 org.apache.flink.formats.csv.PythonCsvUtils.createCsvReaderFormat(schema._j_schema, _to_java_data_type(schema._row_type)) 完成桥接。docstring 给出的完整示例:
from pyflink.common import WatermarkStrategy, Types
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSource
from pyflink.datastream.formats.csv import CsvSchema, CsvReaderFormat
from pyflink.table import DataTypes
schema = CsvSchema.builder() \
.add_number_column('id', number_type=DataTypes.INT()) \
.add_string_column('name') \
.add_array_column('list', ',', element_type=DataTypes.STRING()) \
.set_column_separator('|') \
.set_escape_char('\\') \
.set_use_header() \
.set_strict_headers() \
.build()
source = FileSource.for_record_stream_format(
CsvReaderFormat.for_schema(schema), CSV_FILE_PATH).build()
ds = env.from_source(source, WatermarkStrategy.no_watermarks(), 'csv-source')
# 记录类型为 Types.ROW_NAMED(['id', 'name', 'list'],
# [Types.INT(), Types.STRING(), Types.LIST(Types.STRING())])
测试 test_csv.py 逐一验证了基础列(tinyint/smallint/int/bigint/float/double/decimal/boolean/string)、数组列(三种元素类型与三种分隔符)、注释行、表头、严格表头、默认/自定义引号符、转义符等读取场景,其中数组列测试使用 1;2;3|true:false|a,b,c 这样的混合分隔符数据。
3.3 CsvBulkWriters:批量写出 CSV 文件
CsvBulkWriters.for_schema(schema)(csv.py)返回 RowDataBulkWriterFactory,内部走 org.apache.flink.formats.csv.PythonCsvUtils.createCsvBulkWriterFactory,按预定义 Schema 把 Row 批量写入分区 CSV 文件:
from pyflink.datastream.connectors.file_system import FileSink
from pyflink.datastream.formats.csv import CsvSchema, CsvBulkWriters
schema = CsvSchema.builder() \
.add_number_column('id', number_type=DataTypes.INT()) \
.add_string_column('name') \
.add_array_column('list', ',', element_type=DataTypes.STRING()) \
.set_column_separator('|') \
.build()
sink = FileSink.for_bulk_format(
OUTPUT_DIR, CsvBulkWriters.for_schema(schema)).build()
ds.sink_to(sink)
写出测试 test_csv.py 校验了写回文件的内容,例如基础列一行会写为 '127,-32767,2147483647,-9223372036854775808,3.0E38,2.0E-308,2,true,string\n',含转义符的字符串列会写为 '"string,","""string2"""\n'。
3.4 CsvRow 序列化与反序列化 Schema
CsvRowDeserializationSchema 与 CsvRowSerializationSchema(csv.py)各自内嵌一个 Builder,用于把 Flink 类型对象序列化为 CSV 字节(或反向解析)。两者 Builder 构造时都要求非空的 TypeInformation,否则抛 TypeError("Type information must not be None")。
CsvRowDeserializationSchema.Builder 提供的方法:set_field_delimiter、set_allow_comments、set_array_element_delimiter、set_quote_character、set_escape_character、set_null_literal、set_ignore_parse_errors。
CsvRowSerializationSchema.Builder 提供的方法:set_field_delimiter、set_line_delimiter、set_array_element_delimiter、disable_quote_character、set_quote_character、set_escape_character、set_null_literal。
测试 test_csv.py 展示了二者的配套用法:用 ; 做字段分隔符、* 做转义符、' 做引号符、: 做数组元素分隔符,序列化后再反序列化回原 Row,验证了 "123'4*" → '123''4**'、"a;b'c" → 'a;b''c' 这类转义往返。
from pyflink.common import Types
from pyflink.datastream.formats.csv import (
CsvRowSerializationSchema, CsvRowDeserializationSchema)
row_info = Types.ROW([Types.STRING(), Types.INT(), Types.STRING()])
csv_row_serialization_schema = CsvRowSerializationSchema.Builder(row_info) \
.set_escape_character('*').set_quote_character('\'') \
.set_array_element_delimiter(':').set_field_delimiter(';').build()
csv_row_deserialization_schema = CsvRowDeserializationSchema.Builder(row_info) \
.set_escape_character('*').set_quote_character('\'') \
.set_array_element_delimiter(':').set_field_delimiter(';').build()
四、JSON:Row 与 JSON 字节的双向转换
JSON 子模块在 json.py 中仅提供两个类,但都是 Builder 模式、使用便捷,特别适合 Kafka 等消息管道的 JSON 数据接入/输出。
4.1 JsonRowDeserializationSchema
JsonRowDeserializationSchema.Builder(json.py)支持两种结果类型声明方式:
type_info(type_info):直接用TypeInformation描述结果类型,Row 的字段名用于匹配 JSON 属性;json_schema(json_schema):传入 JSON Schema 字符串,内部通过 Java 的org.apache.flink.formats.json.JsonRowSchemaConverter.convert(json_schema)转换为类型信息(json.py)。
另有三个开关:
fail_on_missing_field():JSON 中缺少字段时直接失败;默认行为是忽略缺失字段并将该字段置为 null;ignore_parse_errors():解析失败时抛出异常(docstring 措辞为“Configures schema to fail when parsing json failed”,即开启后解析失败即报错,默认容错忽略解析错误)。
from pyflink.common import Types
from pyflink.datastream.formats.json import JsonRowDeserializationSchema
row_schema = Types.ROW_NAMED(["svt", "ops", "ids"],
[Types.STRING(),
Types.ROW_NAMED(['id'], [Types.STRING()]),
Types.PRIMITIVE_ARRAY(Types.INT())])
json_row_deserialization_schema = JsonRowDeserializationSchema.builder() \
.type_info(row_schema).build()
# 或使用 JSON Schema 字符串:
# json_row_deserialization_schema = JsonRowDeserializationSchema.builder() \
# .json_schema('{"type":"object","properties":{...}}').build()
4.2 JsonRowSerializationSchema
JsonRowSerializationSchema.Builder(json.py)只有一个必填方法 with_type_info(type_info),未设置时 build() 会抛 TypeError("Typeinfo should be set.")。底层调用 Java 的 JsonRowSerializationSchema.builder().withTypeInfo(...).build()。
from pyflink.datastream.formats.json import JsonRowSerializationSchema
json_row_serialization_schema = JsonRowSerializationSchema.builder() \
.with_type_info(row_schema).build()
测试 test_json.py 演示了完整的往返链路:反序列化 {"svt":"2020-02-24T12:58:09.209+0800"} 这类 JSON 后,再序列化会得到 {"svt":"2020-02-24T12:58:09.209+0800","ops":null,"ids":null},即缺失的嵌套对象与数组字段会被补齐为 null,保证 Row 结构完整。
五、ORC:批量写出 ORC 列式文件
ORC 子模块在 orc.py 中仅提供 OrcBulkWriters.for_row_type 一个静态方法,用于把 Row 批量写入 ORC 文件(当前版本不提供 Python 侧的 ORC 读入格式,读取一般借助 pyflink.table 或外部工具)。
5.1 OrcBulkWriters.for_row_type
方法签名(orc.py):
for_row_type(row_type: RowType,
writer_properties: Optional[Configuration] = None,
hadoop_config: Optional[Configuration] = None) -> BulkWriterFactory
row_type:记录的 RowType,必须与 Row 记录的 RowTypeInfo 一致,非RowType实例会抛TypeError;writer_properties:ORC writer 选项,默认为空Configuration();hadoop_config:Hadoop 配置,默认为空Configuration()。
底层实现路径清晰可循:先把 RowType 转为 Java LogicalType,取出子类型数组,用 org.apache.flink.orc.OrcSplitReaderUtil.logicalTypeToOrcType(j_row_type) 将 Flink 逻辑类型映射为 ORC 类型描述,再组合 RowDataVectorizer(type_description.toString(), orc_types) 与 OrcBulkWriterFactory 构建出 RowDataBulkWriterFactory(orc.py)。writer_properties 会经 create_java_properties 转为 Java Properties,hadoop_config 经 create_hadoop_configuration 转为 Hadoop Configuration。
from pyflink.common import Configuration
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSink
from pyflink.datastream.formats.orc import OrcBulkWriters
from pyflink.table import DataTypes
row_type = DataTypes.ROW([
DataTypes.FIELD('string', DataTypes.STRING()),
DataTypes.FIELD('int_array', DataTypes.ARRAY(DataTypes.INT()))
])
sink = FileSink.for_bulk_format(
OUTPUT_DIR, OrcBulkWriters.for_row_type(
row_type=row_type,
writer_properties=Configuration(),
hadoop_config=Configuration(),
)
).build()
ds.sink_to(sink)
测试 test_orc.py 需要 HADOOP_CLASSPATH 环境变量,覆盖了基础列(char/varchar/bytes/boolean/decimal/int/bigint/double/date/timestamp)以及从 Parquet 测试复用的数组列、map 列写出场景,并用 pd.read_orc 回读校验。
六、Parquet:Avro 记录读写与列式 Row 格式
Parquet 子模块在 parquet.py 中提供四类 API,覆盖两种数据模型:Avro GenericRecord 模型的读写(AvroParquetReaders/AvroParquetWriters)和 Flink Row/RowData 列式模型的读写(ParquetColumnarRowInputFormat/ParquetBulkWriters)。
6.1 AvroParquetReaders / AvroParquetWriters:Avro 模型
AvroParquetReaders.for_generic_record(schema)(parquet.py)读取 Parquet 文件为 Avro GenericRecord,当前仅支持 GenericRecord。docstring 解释了一个重要设计原因:Flink 需要在数据流搭建的 pre-flight 阶段就能序列化结果,而 Schema 虽然存储在 Parquet 文件头中,但那时还无法访问文件,因此必须显式传入 AvroSchema。
from pyflink.common import WatermarkStrategy
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSource
from pyflink.datastream.formats.avro import AvroSchema
from pyflink.datastream.formats.parquet import AvroParquetReaders
env = StreamExecutionEnvironment.get_execution_environment()
schema = AvroSchema.parse_string(JSON_SCHEMA)
source = FileSource.for_record_stream_format(
AvroParquetReaders.for_generic_record(schema), PARQUET_FILE_PATH).build()
ds = env.from_source(source, WatermarkStrategy.no_watermarks(), "parquet-source")
AvroParquetWriters.for_generic_record(schema)(parquet.py)与 Avro 的批量写出约束完全一致:前置算子输出类型需为 GenericRecordAvroTypeInfo,且不能直接来自 from_collection,需加透传 map:
from pyflink.common.typeinfo import Types
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSink
from pyflink.datastream.formats.avro import AvroSchema, GenericRecordAvroTypeInfo
from pyflink.datastream.formats.parquet import AvroParquetWriters
env = StreamExecutionEnvironment.get_execution_environment()
schema = AvroSchema.parse_string(JSON_SCHEMA)
ds = env.from_collection([{'array': [1, 2]}], type_info=Types.PICKLED_BYTE_ARRAY())
sink = FileSink.for_bulk_format(
OUTPUT_DIR, AvroParquetWriters.for_generic_record(schema)).build()
ds.map(lambda e: e, output_type=GenericRecordAvroTypeInfo(schema)).sink_to(sink)
6.2 ParquetColumnarRowInputFormat:列式批读
ParquetColumnarRowInputFormat(parquet.py)是一个提供 RowData 迭代器的 BulkFormat,用 ColumnarRowData 提供列批的行视图。构造函数参数:
row_type:行类型;hadoop_config:Hadoop 配置,默认空Configuration();batch_size:批大小,默认2048;is_utc_timestamp:是否按 UTC 解释时间戳,默认False;is_case_sensitive:是否大小写敏感,默认True。
限制:列仅支持基础(primitive)类型,array、map 等复合类型不支持。内部构造 Java 的 org.apache.flink.formats.parquet.ParquetColumnarRowInputFormat,产出类型为 InternalTypeInfo.of(j_row_type),需配合 FileSource.for_bulk_file_format 使用:
from pyflink.common import Configuration, WatermarkStrategy
from pyflink.datastream import StreamExecutionEnvironment
from pyflink.datastream.connectors.file_system import FileSource
from pyflink.datastream.formats.parquet import ParquetColumnarRowInputFormat
from pyflink.table import DataTypes
row_type = DataTypes.ROW([
DataTypes.FIELD('a', DataTypes.INT()),
DataTypes.FIELD('b', DataTypes.STRING()),
])
source = FileSource.for_bulk_file_format(ParquetColumnarRowInputFormat(
row_type=row_type,
hadoop_config=Configuration(),
batch_size=2048,
is_utc_timestamp=False,
is_case_sensitive=True,
), PARQUET_FILE_PATH).build()
ds = env.from_source(source, WatermarkStrategy.no_watermarks(), "parquet-source")
6.3 ParquetBulkWriters:RowData 批量写出
ParquetBulkWriters.for_row_type(row_type, hadoop_config=None, utc_timestamp=False)(parquet.py)返回 RowDataBulkWriterFactory,内部通过 org.apache.flink.formats.parquet.row.ParquetRowDataBuilder.createWriterFactory(logicalType, hadoopConfiguration, utcTimestamp) 构建。utc_timestamp 参数用于选择 epoch 时间与 LocalDateTime 转换所使用的时区:Hive 0.x/1.x/2.x 使用本地时区,而 Hive 3.x 使用 UTC 时区(见 parquet.py 的 docstring),跨版本读写时需按需设置。
from pyflink.common import Configuration
from pyflink.datastream.connectors.file_system import FileSink
from pyflink.datastream.formats.parquet import ParquetBulkWriters
from pyflink.table import DataTypes
row_type = DataTypes.ROW([
DataTypes.FIELD('string', DataTypes.STRING()),
DataTypes.FIELD('int_array', DataTypes.ARRAY(DataTypes.INT()))
])
sink = FileSink.for_bulk_format(
OUTPUT_DIR, ParquetBulkWriters.for_row_type(
row_type,
hadoop_config=Configuration(),
utc_timestamp=True,
)
).build()
ds.sink_to(sink)
测试 test_parquet.py 同样依赖 HADOOP_CLASSPATH,覆盖了 Avro Parquet 读写(basic/enum/union/array/map)、列式行读取(含 char/varchar/binary/varbinary/boolean/decimal/int/bigint/double/date/time/timestamp/timestamp_ltz 等完整类型族),以及 RowData 写出的数组列场景;其中 test_parquet_row_data_map_write 因“ParquetSchemaConverter 将 map 键标记为 optional 而 Arrow 要求 required”这一已知矛盾被显式 skip。
七、选型与实战要点小结
围绕五类格式,可总结如下选型建议与工程要点:
- 文件 Source 侧:Avro 文件用
AvroInputFormat(输出GenericRecordAvroTypeInfo);CSV 文件用CsvReaderFormat.for_schema(输出Types.ROW_NAMED);Parquet 文件按数据模型二选一——Avro 模型用AvroParquetReaders.for_generic_record,Row/RowData 列式模型用ParquetColumnarRowInputFormat。 - 文件 Sink 侧:四类格式均通过
FileSink.for_bulk_format(output_dir, bulk_writer_factory).build()接入,AvroBulkWriters/CsvBulkWriters/OrcBulkWriters/ParquetBulkWriters分别返回对应的BulkWriterFactory;Avro 系列写出必须为前置算子声明GenericRecordAvroTypeInfo且不能直接来自from_collection。 - 消息管道侧:JSON 与 CSV 提供成对的 Row 序列化/反序列化 Schema,可无缝接入 Kafka 等 Source/Sink;Avro 的 Row 级 Schema 则支持
record_class(高性能)与avro_schema_string(免生成类)两种模式,二者必填其一。 - 版本与依赖:本模块全部 API 自 Flink 1.16.0 引入;ORC/Parquet 相关能力需要 Hadoop classpath(测试用例中以
HADOOK_CLASSPATH为跳过条件),Avro 逻辑日期时间类型需要 JodaTime 依赖;Parquet 时间戳写出需按 Hive 版本选择utc_timestamp。 - 参考实现:所有类的行为都有同目录测试佐证——test_avro.py、test_csv.py、test_json.py、test_orc.py、test_parquet.py,它们是调试与理解格式语义的最佳参考。
如需查看 Java 侧实现细节,可继续深入 flink-formats 目录下的 flink-avro、flink-csv、flink-json、flink-orc、flink-parquet 各模块。