FileSystem连接器
概述
FileSystem连接器用于在AI DataLake的Flink作业中实现与文件系统的数据交互。该连接器支持对本地文件系统、对象存储服务OBS等存储后端的批流统一读写,提供多文件格式和分区写入能力,适用于数据归档、文件导出和批处理ETL等场景。
| 类别 | 详情 |
|---|---|
| 支持类型 | 源表和结果表 |
| 数据格式 | CSV,JSON,Avro,Parquet,Orc,Debezium-JSON,Canal-JSON,Raw |
| API种类 | SQL,Datastream |
| 是否支持更新或删除结果表数据 | 否 |
适用场景
- 数据归档:将流式数据按时间分区滚动写入HDFS或OBS,实现长期归档存储。
- 文件导出:将处理结果以CSV或JSON格式导出到文件系统,供下游系统消费。
- 批处理ETL:从文件系统批量读取数据,清洗转换后写入目标存储。
- 列式存储优化:以Parquet或ORC格式写入文件,提升下游查询性能。
- 多源数据汇聚:将多个数据源的数据统一写入文件系统,构建数据湖。
约束与限制
- 文件格式需与format参数配置一致,否则读取时会报错。
- Exactly-Once语义依赖Checkpoint机制,需确保Checkpoint正常触发且间隔合理。
语法结构
Source
CREATE TABLE fs_source (
{column_name} {column_type},
...
) WITH (
'connector' = 'filesystem',
'path' = '{file_system_path}',
'format' = '{file_format}'
); Sink
CREATE TABLE fs_sink (
{column_name} {column_type},
...
) PARTITIONED BY ({partition_columns}) WITH (
'connector' = 'filesystem',
'path' = '{file_system_path}',
'format' = '{file_format}',
'sink.rolling-policy.file-size' = '{size}',
'sink.rolling-policy.rollover-interval' = '{interval}'
); WITH参数说明
公共参数
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| connector | 是 | String | 无 | filesystem | 指定连接器类型为FileSystem连接器。 该参数为固定值,不可修改。配置时必须设置为filesystem,系统根据此值加载对应的文件系统连接器实现。 |
| path | 是 | String | 无 | 有效的文件系统路径 | 指定文件系统的读写路径。 支持本地路径(file:///)、OBS路径(obs://)等。配置时需确保Flink作业对该路径有读写权限。 |
| format | 是 | String | 无 | csv、json、avro、parquet、orc | 指定文件的序列化格式。
配置时需根据数据特性和查询需求选择。 |
Source专有参数
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| source.monitor-interval | 否 | Duration | 无 | 有效的持续时间,如10s、1min | 指定流式模式下监控目录新文件的时间间隔。 配置后Source将周期性扫描目录,发现新文件时自动读取。未配置时为批式读取模式,仅读取一次目录下所有文件。配置时需根据文件生成频率调整扫描间隔。 |
Sink专有参数
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| sink.rolling-policy.file-size | 否 | MemorySize | 128MB | 有效的内存大小,如64mb、256mb | 指定滚动文件的目标大小。 当单个文件达到该大小时滚动生成新文件。配置时需在文件数量和单文件大小之间权衡,文件过小产生过多小文件影响查询性能,文件过大影响写入延迟。 |
| sink.rolling-policy.rollover-interval | 否 | Duration | 30min | 有效的持续时间,如30s、5min | 指定滚动文件的时间间隔。 当文件打开时间超过该间隔时滚动生成新文件。配置时需根据数据可见性需求调整,间隔过短产生过多小文件,间隔过长数据延迟高。 |
| sink.rolling-policy.check-interval | 否 | Duration | 60s | 有效的持续时间,如30s、5min | 基于时间的滚动策略检查间隔。 该参数用于控制检查部分文件(part file)是否应根据 sink.rolling-policy.rollover-interval 参数进行滚动的频率。 |
| sink.partition-commit.policy.kind | 否 | String | 无 | success-file、metadata、success-file+metadata | 指定分区提交策略。
配置后系统在分区数据写入完成后触发提交动作,通知下游分区已就绪。 |
| sink.partition-commit.delay | 否 | Duration | 0s | 有效的持续时间,如1min、10min | 指定分区提交的延迟时间。 分区数据写入完成后等待该时间再提交,用于确保延迟到达的数据写入正确分区。配置时需根据数据延迟情况设定,延迟过短可能导致数据写入错误分区。 |
| sink.partition-commit.trigger | 否 | String | process-time | process-time、partition-time | 指定分区提交的触发器类型。
配置时建议使用partition-time以保证数据一致性。 |
| auto-compaction | 否 | Boolean | false | true、false | 指定是否启用自动文件合并。 启用后系统在Checkpoint提交时自动合并小文件为目标大小的文件。配置时建议在滚动间隔较短产生大量小文件的场景下开启。 |
| compaction.file-size | 否 | MemorySize | 无 | 有效的内存大小,如128mb、256mb | 指定文件合并后的目标文件大小。 仅在auto-compaction为true时生效。配置时需与sink.rolling-policy.file-size协调,建议设置为file-size的1至2倍。 |
使用示例
- 示例1:批式读取HDFS上的CSV文件,输出到Print结果表。
-- 创建FileSystem源表(CSV格式,批式读取) CREATE TABLE fs_csv_source ( order_id BIGINT, user_id BIGINT, amount DOUBLE, order_time TIMESTAMP(3) ) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/orders/', 'format' = 'csv' ); -- 创建Print结果表 CREATE TABLE print_sink ( order_id BIGINT, user_id BIGINT, amount DOUBLE, order_time TIMESTAMP(3) ) WITH ( 'connector' = 'print', 'print-identifier' = 'fs_csv_orders' ); -- 提交作业 INSERT INTO print_sink SELECT order_id, user_id, amount, order_time FROM fs_csv_source;
- 示例2:使用DataGen生成模拟数据,以Parquet列式格式按天分区写入HDFS。
-- 创建DataGen源表 CREATE TABLE event_source ( event_id BIGINT, event_type STRING, event_time TIMESTAMP(3), dt STRING ) WITH ( 'connector' = 'datagen', 'rows-per-second' = '200', 'fields.event_id.kind' = 'sequence', 'fields.event_id.start' = '1', 'fields.event_id.end' = '1000000', 'fields.event_type.length' = '10', 'fields.dt.kind' = 'sequence', 'fields.dt.start' = '20260101', 'fields.dt.end' = '20260131' ); -- 创建FileSystem Sink结果表(Parquet格式,按天分区) CREATE TABLE fs_parquet_sink ( event_id BIGINT, event_type STRING, event_time TIMESTAMP(3), dt STRING ) PARTITIONED BY (dt) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/events/', 'format' = 'parquet', 'sink.rolling-policy.file-size' = '256mb', 'sink.rolling-policy.rollover-interval' = '5min', 'sink.partition-commit.policy.kind' = 'success-file', 'sink.partition-commit.trigger' = 'partition-time' ); -- 提交作业 INSERT INTO fs_parquet_sink SELECT event_id, event_type, event_time, dt FROM event_source;
- 示例3:流式监控HDFS目录下新增的JSON文件,实时输出到Print结果表。
-- 创建FileSystem源表(JSON格式,流式监控) CREATE TABLE fs_json_source ( log_id BIGINT, log_level STRING, log_message STRING, log_time TIMESTAMP(3) ) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/logs/', 'format' = 'json', 'source.monitor-interval' = '10s' ); -- 创建Print结果表 CREATE TABLE log_print_sink ( log_id BIGINT, log_level STRING, log_message STRING, log_time TIMESTAMP(3) ) WITH ( 'connector' = 'print', 'print-identifier' = 'fs_json_logs' ); -- 提交作业 INSERT INTO log_print_sink SELECT log_id, log_level, log_message, log_time FROM fs_json_source;
- 示例4:从Kafka消费订单数据,以ORC列式格式按小时分区写入HDFS,启用自动文件合并。
-- 创建Kafka源表 CREATE TABLE kafka_order_source ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, event_time TIMESTAMP(3), WATERMARK FOR event_time AS event_time - INTERVAL '5' SECOND, dt STRING, hh STRING ) WITH ( 'connector' = 'kafka', 'topic' = 'orders', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'fs_orc_group', 'scan.startup.mode' = 'latest-offset', 'format' = 'json', 'json.ignore-parse-errors' = 'true' ); -- 创建FileSystem Sink结果表(ORC格式,按天+小时分区) CREATE TABLE fs_orc_sink ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, event_time TIMESTAMP(3), dt STRING, hh STRING ) PARTITIONED BY (dt, hh) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/orders_orc/', 'format' = 'orc', 'sink.rolling-policy.file-size' = '128mb', 'sink.rolling-policy.rollover-interval' = '1min', 'sink.partition-commit.policy.kind' = 'success-file', 'sink.partition-commit.trigger' = 'partition-time', 'auto-compaction' = 'true', 'compaction.file-size' = '256mb' ); -- 提交ETL作业 INSERT INTO fs_orc_sink SELECT order_id, user_id, amount, status, event_time, DATE_FORMAT(event_time, 'yyyy-MM-dd') AS dt, DATE_FORMAT(event_time, 'HH') AS hh FROM kafka_order_source; - 示例5:批式读取HDFS上的Avro文件,过滤后以JSON格式写入另一个HDFS目录。
-- 创建FileSystem源表(Avro格式) CREATE TABLE fs_avro_source ( user_id BIGINT, user_name STRING, age INT, city STRING, register_time TIMESTAMP(3) ) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/users_avro/', 'format' = 'avro' ); -- 创建FileSystem Sink结果表(JSON格式) CREATE TABLE fs_json_sink ( user_id BIGINT, user_name STRING, age INT, city STRING, register_time TIMESTAMP(3) ) WITH ( 'connector' = 'filesystem', 'path' = 'obs://xxx/data/users_json/', 'format' = 'json', 'sink.rolling-policy.file-size' = '128mb', 'sink.rolling-policy.rollover-interval' = '5min' ); -- 提交作业:过滤成年用户 INSERT INTO fs_json_sink SELECT user_id, user_name, age, city, register_time FROM fs_avro_source WHERE age >= 18;
- 示例6:使用DataGen生成模拟数据,以CSV格式写入本地文件系统,适用于本地测试场景。
-- 创建DataGen源表 CREATE TABLE metric_source ( metric_id BIGINT, metric_name STRING, metric_value DOUBLE, metric_time TIMESTAMP(3) ) WITH ( 'connector' = 'datagen', 'rows-per-second' = '100', 'fields.metric_id.kind' = 'sequence', 'fields.metric_id.start' = '1', 'fields.metric_id.end' = '100000', 'fields.metric_name.length' = '15', 'fields.metric_value.min' = '0.0', 'fields.metric_value.max' = '100.0' ); -- 创建FileSystem Sink结果表(CSV格式,本地文件系统) CREATE TABLE fs_local_csv_sink ( metric_id BIGINT, metric_name STRING, metric_value DOUBLE, metric_time TIMESTAMP(3) ) WITH ( 'connector' = 'filesystem', 'path' = 'file:///tmp/flink/metrics/', 'format' = 'csv', 'sink.rolling-policy.file-size' = '64mb', 'sink.rolling-policy.rollover-interval' = '30s' ); -- 提交作业 INSERT INTO fs_local_csv_sink SELECT metric_id, metric_name, metric_value, metric_time FROM metric_source;