# FileSystem连接器
#### 概述
FileSystem连接器用于在AI DataLake的Flink作业中实现与文件系统的数据交互。该连接器支持对[本地文件系统](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/connectors/table/filesystem/)、[对象存储服务OBS](https://support.huaweicloud.com/productdesc-obs/zh-cn_topic_0045829060.html)等存储后端的批流统一读写，提供多文件格式和分区写入能力，适用于数据归档、文件导出和批处理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;
  ```
  
 
