更新时间:2026-11-06 GMT+08:00
分享

FileSystem连接器

概述

FileSystem连接器用于在AI DataLake的Flink作业中实现与文件系统的数据交互。该连接器支持对本地文件系统、对象存储服务OBS等存储后端的批流统一读写,提供多文件格式和分区写入能力,适用于数据归档、文件导出和批处理ETL等场景。

表1 连接器详情

类别

详情

支持类型

源表和结果表

数据格式

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

指定文件的序列化格式。

  • csv为逗号分隔的文本格式
  • json为JSON行格式
  • avro为Apache Avro行式格式
  • parquet为列式存储格式
  • orc为Optimized Row Columnar列式格式

配置时需根据数据特性和查询需求选择。

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

指定分区提交策略。

  • success-file表示提交时创建_SUCCESS标记文件。
  • metadata表示提交时写入分区元数据。

配置后系统在分区数据写入完成后触发提交动作,通知下游分区已就绪。

sink.partition-commit.delay

否

Duration

0s

有效的持续时间,如1min、10min

指定分区提交的延迟时间。

分区数据写入完成后等待该时间再提交,用于确保延迟到达的数据写入正确分区。配置时需根据数据延迟情况设定,延迟过短可能导致数据写入错误分区。

sink.partition-commit.trigger

否

String

process-time

process-time、partition-time

指定分区提交的触发器类型。

  • process-time表示基于系统处理时间触发提交。
  • partition-time表示基于分区时间(Watermark)触发提交。

配置时建议使用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;

相关文档