Kafka连接器
概述
Kafka连接器用于从DMS Kafka主题(Topic)读取数据或将数据写入DMS Kafka主题,是最常用的流式数据连接器,支持精确一次(Exactly-Once)语义保证。
| 类别 | 详情 |
|---|---|
| 支持类型 | 源表和结果表,数据摄入目标端 |
| 运行模式 | 流模式 |
| 数据格式 | 详情请参见Formats。 |
| API种类 | SQL,Datastream |
| 是否支持更新或删除结果表数据 | 不支持更新和删除结果表数据,只支持插入数据。 更新和删除数据相关功能请参见Upsert-Kafka连接器。 |
适用场景
- 实时数据采集:从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参数说明
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| 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。
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等)。 |
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| 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;