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

Kafka连接器

概述

Kafka连接器用于从DMS Kafka主题(Topic)读取数据或将数据写入DMS Kafka主题,是最常用的流式数据连接器,支持精确一次(Exactly-Once)语义保证。

表1 连接器详情

类别

详情

支持类型

源表和结果表,数据摄入目标端

运行模式

流模式

数据格式

详情请参见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参数说明

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;

相关文档