# Kafka连接器
#### 概述
Kafka连接器用于从[DMS Kafka主题（Topic）](https://support.huaweicloud.com/productdesc-kafka/kafka-pd-190605001.html)读取数据或将数据写入DMS Kafka主题，是最常用的流式数据连接器，支持精确一次（Exactly-Once）语义保证。
表1连接器详情 
| **类别**         | **详情**                                                                                                                                                                       |
|:---|:---|
| 支持类型            | 源表和结果表，数据摄入目标端                                                                                                                                                              |
| 运行模式             | 流模式                                                                                                                                                                        |
| 数据格式           | 详情请参见[Formats](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/connectors/table/formats/overview/)。                                                        |
| API种类         | SQL，Datastream                                                                                                                                                               |
| 是否支持更新或删除结果表数据 | 不支持更新和删除结果表数据，只支持插入数据。 更新和删除数据相关功能请参见[Upsert-Kafka连接器](https://support.huaweicloud.com/sqlref-flink-aidatalake/aidatalake_11_0005.html)。 |
   
#### 适用场景
- **实时数据采集**：从Kafka消费消息，进行流式处理和分析。
- **数据管道**：将处理后的结果数据写入Kafka，供下游系统消费。
- **事件驱动架构**：基于Kafka消息触发实时计算和响应。
- **数据集成**：作为不同系统间的消息中间件，实现数据流转。
- **CDC数据捕获**：配合Debezium/Canal格式，实现变更数据捕获。
 
#### 约束与限制
- 消费者偏移量提交行为：开启Checkpoint时在Checkpoint完成时提交；未开启时依赖Kafka Consumer自动提交。
- 默认消费数据时，topic须提前创建。
- DMS Kafka需要为3.x及以上版本。
 
#### 语法结构
```
CREATE TABLE {table_name} (
  {column_name} {column_type},
  ...
) WITH (
  'connector' = 'kafka',
  'topic' = '{kafka_topic}',
  'properties.bootstrap.servers' = '{broker_list}',
  'properties.group.id' = '{consumer_group}',
  'scan.startup.mode' = '{startup_mode}',
  'format' = '{data_format}',
  '{format_specific_param}' = '{value}'
);
```
#### WITH参数说明
**Source参数**
| 参数                                    | 是否必填 | 类型      | 默认值         | 取值范围                                                                           | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|:---|:---|:---|:---|:---|:---|
| connector                             | 是   | String    | 无            | kafka                                                                          | 标识连接器类型为Kafka连接器。 必须填写且值固定为kafka。Flink运行时根据此值加载对应的Kafka Source/Sink工厂类，将表声明为Kafka数据源或输出表。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| topic                                  | 是  | String   | 无          | 有效的Topic名                                                                       | 指定消费的Kafka主题名称。 Source必填，支持分号分隔的多个Topic（如topic-a;topic-b）。Flink运行时为每个Topic分区分配一个子任务并行消费，多个Topic的分区将被合并调度。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| properties.bootstrap.servers           | 是   | String | 无           | host:port列表                                                                    | 指定Kafka Broker地址列表，多个地址以逗号分隔。 Source和Sink均必填。Flink运行时使用此配置创建Kafka Consumer或Producer客户端连接，建议配置多个Broker地址以实现高可用。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| properties.group.id                  | 否    | String   | 无           | 有效的消费者组名                                                                       | 指定Kafka消费者组ID。 Source必填。Flink运行时使用此组ID标识消费者身份，相同组ID的消费者共享Topic分区的消费进度，不同作业应使用不同的group.id以避免分区分配冲突。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| scan.startup.mode                     | 否  | String     | group-offsets | earliest-offset / latest-offset / group-offsets / specific-offsets / timestamp | 指定Source首次消费时的起始位置模式。 默认为group-offsets。 - 当设置为specific-offsets时需配合scan.startup.specific-offsets使用。  - 当设置为timestamp时需配合scan.startup.timestamp-millis使用。   Flink运行时根据此模式确定Kafka Consumer的初始消费位移，影响作业启动时的数据读取起点。 |
| scan.startup.specific-offsets          | 否  | String   | 无            | partition:offset列表                                                             | 指定各分区的起始偏移量。 仅在scan.startup.mode为specific-offsets时生效。格式为partition:offset,partition:offset。Flink运行时将Kafka Consumer的各分区初始位移设置到指定位置，从未消费过的分区将从该偏移量开始读取。                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| scan.startup.timestamp-millis           | 否   | Long      | 无          | 毫秒时间戳                                                                          | 指定消费起始时间戳（毫秒）。 仅在scan.startup.mode为timestamp时生效。Flink运行时将Kafka Consumer的起始位移定位到不早于该时间戳的第一条消息，适用于从特定时间点恢复数据消费。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| format                                 | 是    | String   | 无         | json / csv / avro / debezium-json / canal-json / raw                            | 指定消息的反序列化格式。 Source和Sink均必填。Flink运行时根据此值加载对应的Format工厂类，将Kafka消息字节流与Flink表行数据进行相互转换。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| scan.topic-partition-discovery.interval | 否    | Duration | 5min         | 有效的持续时间，如30s、5min                                                                                             | 设置动态分区发现的检查间隔。 设置后可自动发现Topic新增分区，无需重启作业。Flink运行时启动后台线程按此间隔定期查询Topic元数据，发现新分区后自动分配给空闲子任务消费。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| properties.\*                            | 否    | String     | -            | Kafka Consumer配置                                                                | 传递给Kafka Consumer的任意配置参数，前缀为properties.。 配置项名称去掉properties.前缀后直接透传给Kafka Consumer。Flink运行时在创建Kafka客户端时将这些参数原样传入，可用于调整消费行为（如fetch.min.bytes、max.poll.records等）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
   
**Sink参数**
| 参数                            | 是否必填 | 类型       | 默认值          | 取值范围                                                  | 说明                                                                                                                                                                                                                                   |
|:---|:---|:---|:---|:---|:---|
| connector                     | 是     | String | 无            | kafka                                                | 标识连接器类型为Kafka连接器。 必须填写且值固定为kafka。Flink运行时根据此值加载对应的Kafka Source/Sink工厂类，将表声明为Kafka数据源或输出表。                                                                           |
| topic                        | 是   | String | 无             | 有效的Topic名                                            | 指定写入的Kafka主题名称。 Sink必填。Flink运行时将所有输出记录发送到此Topic，如Topic不存在需预先创建或开启Kafka自动创建Topic配置。                                                                                   |
| properties.bootstrap.servers | 是    | String  | 无             | host:port列表                                         | 指定Kafka Broker地址列表，多个地址以逗号分隔。 Source和Sink均必填。Flink运行时使用此配置创建Kafka Consumer或Producer客户端连接，建议配置多个Broker地址以实现高可用。                                                   |
| format                        | 是  | String | 无            | json / csv / avro / debezium-json / canal-json / raw | 指定消息的序列化格式。 Sink必填。Flink运行时根据此值将Flink表行数据序列化为对应格式的字节流写入Kafka。                                                                                                      |
| sink.partitioner            | 否    | String  | default       | default / fixed / round-robin / 自定义类全限定名            | 指定写入Kafka的分区策略。 默认为default。default按Key哈希分区（无Key时轮询）；fixed每个Sink子任务固定写一个分区；round-robin轮询所有分区。Flink运行时根据此策略决定每条记录发送到Kafka的哪个分区，影响数据在分区间的分布均衡性。                     |
| sink.semantic                 | 否    | String   | at-least-once | at-least-once / exactly-once / none                  | 指定写入的语义保证级别。 默认为at-least-once。设置为exactly-once时需开启Flink Checkpoint机制。Flink运行时在at-least-once模式下每条记录立即提交；exactly-once模式下使用Kafka事务在Checkpoint完成时才提交数据，确保数据不重复但会增加延迟。 |
| properties.\*                 | 否    | String  | -              | Kafka Producer配置                                    | 传递给Kafka Producer的任意配置参数，前缀为properties.。 配置项名称去掉properties.前缀后直接透传给Kafka Producer。Flink运行时在创建Kafka Producer时将这些参数原样传入，可用于调整生产行为（如batch.size、linger.ms等）。             |
   
**格式参数**
以下为常用的格式相关参数，通过 format 参数指定格式后生效。
**JSON格式参数**
| 参数                            | 是否必填 | 类型     | 默认值     | 取值范围                | 说明                                                                                                                                                                                                                       |
|:---|:---|:---|:---|:---|:---|
| json.fail-on-missing-field   | 否  | Boolean   | false    | true / false       | 控制当JSON消息中缺少DDL定义的字段时是否报错。 默认为false。设置为true时遇到缺失字段抛出异常导致作业失败；false时将缺失字段置为null继续处理。Flink运行时在反序列化阶段检查每个字段，此参数决定了字段缺失时的容错策略。                                |
| json.ignore-parse-errors       | 否    | Boolean | false   | true / false       | 控制是否忽略JSON解析错误。 默认为false。设置为true时遇到解析错误跳过该字段而非报错，可提高容错性但可能导致数据丢失。Flink运行时在反序列化遇到异常时，true模式将异常字段置为null继续处理后续字段，false模式直接抛出异常终止作业。                       |
| json.timestamp-format.standard | 否  | String    | SQL      | SQL / ISO-8601    | 指定时间戳类型的解析格式标准。 默认为SQL。SQL格式解析为yyyy-MM-dd HH:mm:ss.S；ISO-8601格式解析为yyyy-MM-dd'T'HH:mm:ss.S。Flink运行时根据此标准选择对应的解析器，影响JSON中时间戳字符串与Flink TIMESTAMP类型之间的转换规则。 |
| json.map-null-key.mode         | 否   | String    | FAIL  | FAIL / DROP / LITERAL | 指定Map类型中null键的处理方式。 默认为FAIL。FAIL遇到null键时抛出异常；DROP丢弃null键的键值对；LITERAL将null键替换为指定字符串。Flink运行时在序列化Map数据时根据此策略处理null键，影响包含null键的Map数据的输出行为。                 |
| json.map-null-key.literal       | 否    | String  | "null" | 任意字符串              | 指定当json.map-null-key.mode为LITERAL时null键的替换字符串。 仅在json.map-null-key.mode为LITERAL时生效。Flink运行时在序列化Map数据时，将null键替换为此参数指定的字符串值输出。                            |
   
**CSV格式参数**
| 参数                          | 是否必填 | 类型         | 默认值  | 取值范围          | 说明                                                                                                                                                                                        |
|:---|:---|:---|:---|:---|:---|
| csv.field-delimiter           | 否 | String   | ,     | 单字符            | 指定CSV字段的分隔符。 默认为逗号（,）。仅支持单字符。Flink运行时使用此分隔符拆分或拼接CSV记录的各字段值。                                                            |
| csv.disable-quote-character | 否  | Boolean | false | true / false | 控制是否禁用引号字符。 默认为false。设置为true时引号字符将被视为普通字符处理。Flink运行时在解析CSV时，禁用引号后含分隔符的字段值不再被引号包裹保护，可能导致字段解析错误。                         |
| csv.quote-character           | 否  | String     | "     | 单字符          | 指定CSV中的引号字符，用于包裹含分隔符的字段值。 默认为双引号（"）。仅在csv.disable-quote-character为false时生效。Flink运行时在解析和生成CSV时，使用此字符识别和包裹含有分隔符或换行符的字段值。 |
| csv.allow-comments            | 否   | Boolean   | false  | true / false | 控制是否允许CSV中包含注释行（以#开头）。 默认为false。设置为true时以#开头的行将被跳过。Flink运行时在解析CSV记录时，遇到#开头的行将视为注释忽略，不作为数据记录处理。                          |
| csv.ignore-parse-errors       | 否   | Boolean     | false   | true / false | 控制是否忽略CSV解析错误。 默认为false。设置为true时遇到解析错误的字段置为null继续处理。Flink运行时在反序列化遇到格式异常时，true模式跳过错误字段继续处理后续字段，false模式直接抛出异常终止作业。        |
| csv.array-element-delimiter    | 否   | String    | ;   | 任意字符串       | 指定数组元素的分隔符。 默认为分号（;）。Flink运行时在解析和生成CSV中的数组类型字段时，使用此分隔符拆分或拼接数组元素。                                                          |
   
**Avro格式参数**
| 参数 | 是否必填 | 类型   | 默认值  | 取值范围 | 说明                                                                                                                                                               |
|:---|:---|:---|:---|:---|:---|
| encoding                         | 否   | String | binary | binary / json                        | 指定Avro的编码格式。 binary为二进制编码，json为JSON编码。Flink运行时根据此值选择binary 数据的序列化/反序列化方式，二进制编码更紧凑高效，JSON编码可读性更强。 |
   
#### 使用示例
- **示例1：从Kafka主题消费JSON格式消息，最简配置。**
  ```
  -- 创建Kafka源表
  CREATE TABLE kafka_source (
    user_id BIGINT,
    event_type STRING,
    event_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'kafka',
    'topic' = 'user-events',
    'properties.bootstrap.servers' = 'kafka-broker:9092',
    'properties.group.id' = 'flink-consumer-group',
    'scan.startup.mode' = 'latest-offset',
    'format' = 'json'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    user_id BIGINT,
    event_type STRING,
    event_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'print'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT user_id, event_type, event_time
  FROM kafka_source;
  ```
  
 
- **示例2：从Kafka主题的最早偏移量开始消费，适用于需要全量回放数据的场景。**
  ```
  -- 创建Kafka源表（从最早偏移量消费）
  CREATE TABLE kafka_source_earliest (
    order_id STRING,
    amount DECIMAL(10, 2),
    order_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'kafka',
    'topic' = 'orders',
    'properties.bootstrap.servers' = 'kafka-broker:9092',
    'properties.group.id' = 'order-consumer',
    'scan.startup.mode' = 'earliest-offset',
    'format' = 'json'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    order_id STRING,
    amount DECIMAL(10, 2),
    order_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'print'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT order_id, amount, order_time
  FROM kafka_source_earliest;
  ```
  
- **示例3：从指定时间戳开始消费，适用于从某个时间点恢复数据处理的场景。**
  ```
  -- 创建Kafka源表（从指定时间戳消费）
  CREATE TABLE kafka_source_timestamp (
    log_id STRING,
    log_level STRING,
    message STRING,
    log_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'kafka',
    'topic' = 'application-logs',
    'properties.bootstrap.servers' = 'kafka-broker:9092',
    'properties.group.id' = 'log-consumer',
    'scan.startup.mode' = 'timestamp',
    'scan.startup.timestamp-millis' = '1704067200000',
    'format' = 'json'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    log_id STRING,
    log_level STRING,
    message STRING,
    log_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'print'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT log_id, log_level, message, log_time
  FROM kafka_source_timestamp;
  ```
  
- **示例4：消费CSV格式的Kafka消息，自定义字段分隔符。**
  ```
  -- 创建Kafka源表（CSV格式）
  CREATE TABLE kafka_csv_source (
    id INT,
    name STRING,
    score DOUBLE
  ) WITH (
    'connector' = 'kafka',
    'topic' = 'csv-data',
    'properties.bootstrap.servers' = 'kafka-broker:9092',
    'properties.group.id' = 'csv-consumer',
    'scan.startup.mode' = 'latest-offset',
    'format' = 'csv',
    'csv.field-delimiter' = '|'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    id INT,
    name STRING,
    score DOUBLE
  ) WITH (
    'connector' = 'print'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT id, name, score
  FROM kafka_csv_source;
  ```
  
 
