PyFlink DataStream Formats 完整指南:Avro、CSV、JSON、ORC、Parquet 数据格式的读写实战

原创2026-09-24 13:19:171,747 阅读
文章标签:后端大数据流处理批处理

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 给出了完整的写出链路示例,其中有两个必须注意的约束:

  1. FileSink 的前置算子输出类型必须是 GenericRecordAvroTypeInfo;
  2. 前置算子不能直接是 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。

七、选型与实战要点小结

围绕五类格式,可总结如下选型建议与工程要点:

  1. 文件 Source 侧:Avro 文件用 AvroInputFormat(输出 GenericRecordAvroTypeInfo);CSV 文件用 CsvReaderFormat.for_schema(输出 Types.ROW_NAMED);Parquet 文件按数据模型二选一——Avro 模型用 AvroParquetReaders.for_generic_record,Row/RowData 列式模型用 ParquetColumnarRowInputFormat。
  2. 文件 Sink 侧:四类格式均通过 FileSink.for_bulk_format(output_dir, bulk_writer_factory).build() 接入,AvroBulkWriters/CsvBulkWriters/OrcBulkWriters/ParquetBulkWriters 分别返回对应的 BulkWriterFactory;Avro 系列写出必须为前置算子声明 GenericRecordAvroTypeInfo 且不能直接来自 from_collection。
  3. 消息管道侧:JSON 与 CSV 提供成对的 Row 序列化/反序列化 Schema,可无缝接入 Kafka 等 Source/Sink;Avro 的 Row 级 Schema 则支持 record_class(高性能)与 avro_schema_string(免生成类)两种模式,二者必填其一。
  4. 版本与依赖:本模块全部 API 自 Flink 1.16.0 引入;ORC/Parquet 相关能力需要 Hadoop classpath(测试用例中以 HADOOK_CLASSPATH 为跳过条件),Avro 逻辑日期时间类型需要 JodaTime 依赖;Parquet 时间戳写出需按 Hive 版本选择 utc_timestamp。
  5. 参考实现:所有类的行为都有同目录测试佐证——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 各模块。

登录后查看全文
flink