Upsert-Kafka连接器
概述
Upsert-Kafka连接器是Kafka连接器的变更日志(Changelog)变体,用于以Upsert方式读写DMS Kafka主题(Topic)。与普通Kafka连接器仅处理追加(Append)数据不同,Upsert-Kafka连接器将Kafka消息解释为变更日志记录,支持按主键的插入、更新和删除操作,适用于需要端到端Exactly-Once语义的CDC(Change Data Capture)场景。
| 类别 | 详情 |
|---|---|
| 支持类型 | 源表和结果表 |
| 运行模式 | 流模式 |
| 数据格式 | 详情请参见Formats。 |
| API种类 | SQL,Datastream |
| 是否支持更新或删除结果表数据 | 是 |
适用场景
- CDC数据管道:将Debezium等CDC工具捕获的变更数据以Upsert方式写入Kafka,下游消费时自动按主键合并为最新状态。
- 实时数仓同步:将Flink聚合计算产生的回撤记录(-U/+U)写入Kafka,下游消费者可获取完整的变更语义。
- 跨系统数据同步:作为不同系统间的变更数据传输通道,保证数据一致性。
- 事件溯源:将领域事件以变更日志形式持久化到Kafka,支持状态重建和时间旅行查询。
- 维度表广播:将维度表的变更数据广播到Kafka,下游作业按主键更新本地维度缓存。
约束与限制
- 与普通Kafka连接器(connector = 'kafka')互不兼容,同一Topic不建议混用两种连接器读写。
- 默认消费数据时,topic须提前创建。
- DMS Kafka需要为3.x及以上版本。
与普通Kafka连接器的区别
| 对比项 | Kafka连接器 | Upsert-Kafka连接器 |
|---|---|---|
| connector值 | kafka | upsert-kafka |
| 主键要求 | 不需要 | 必须定义PRIMARY KEY |
| 数据语义 | 追加流(Append-only) | 变更日志流(Changelog) |
| Source输出 | 原始消息 | 按主键去重后的最新状态 |
| Sink写入 | 仅追加写入 | 按主键Upsert写入(更新或插入) |
| 删除支持 | 不支持 | Sink支持删除(-D记录写为NULL值) |
| 适用场景 | 事件流、日志采集 | CDC同步、状态更新、维度广播 |
| 消息格式 | 普通键值对 | Key为主键字段值,Value为完整记录或NULL(删除) |
语法结构
CREATE TABLE {table_name} (
{column_name} {column_type},
...
PRIMARY KEY ({pk_column}) NOT ENFORCED,
WATERMARK FOR {time_column} AS {watermark_expression}
) WITH (
'connector' = 'upsert-kafka',
'topic' = '{kafka_topic}',
'properties.bootstrap.servers' = '{broker_list}',
'properties.group.id' = '{consumer_group}',
'key.format' = '{key_format}',
'value.format' = '{value_format}'
);
Upsert-Kafka连接器必须分别指定Key和Value的序列化格式。Key对应主键字段,Value对应非主键字段。删除记录时Value为NULL。
WITH参数说明
Source参数
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| connector | 是 | String | 无 | upsert-kafka | 标识连接器类型为Upsert-Kafka连接器。 必须填写且值固定为upsert-kafka。Flink运行时根据此值加载Upsert-Kafka Source工厂类,将表声明为变更日志数据源,按主键对消息进行去重合并。 |
| topic | 是 | String | 无 | 有效的Topic名 | 指定消费的Kafka主题名称。 Source必填。Flink运行时为每个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分区的消费进度。 |
| key.format | 是 | String | 无 | json / csv / avro | 指定主键字段的反序列化格式。 Source和Sink均必填。Flink运行时根据此格式将Kafka消息的Key部分(主键字段)进行反序列化。主键字段的序列化/反序列化必须使用与写入时相同的格式。 |
| value.format | 是 | String | 无 | json / csv / avro | 指定非主键字段的反序列化格式。 Source和Sink均必填。Flink运行时根据此格式将Kafka消息的Value部分(非主键字段)进行反序列化。删除记录的Value为NULL。 |
| scan.topic-partition-discovery.interval | 否 | Duration | 无 | 正整数(毫秒) | 设置动态分区发现的检查间隔。 设置后可自动发现Topic新增分区。 |
| properties.* | 否 | String | - | Kafka Consumer配置 | 传递给Kafka Consumer的任意配置参数,前缀为properties.。 配置项名称去掉properties.前缀后直接透传给Kafka Consumer。 |
Sink参数
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| connector | 是 | String | 无 | upsert-kafka | 标识连接器类型为Upsert-Kafka连接器。 必须填写且值固定为upsert-kafka。Flink运行时根据此值加载Upsert-Kafka Sink工厂类,将表声明为变更日志输出表,按主键进行Upsert写入。 |
| topic | 是 | String | 无 | 有效的Topic名 | 指定写入的Kafka主题名称。 Sink必填。Flink运行时将所有输出记录发送到此Topic,Key为主键字段值,Value为完整记录或NULL(删除记录)。 |
| properties.bootstrap.servers | 是 | String | 无 | host:port列表 | 指定Kafka Broker地址列表,多个地址以逗号分隔。Source和Sink均必填。 |
| key.format | 是 | String | 无 | json / csv / avro | 指定主键字段的序列化格式。 Sink必填。Flink运行时根据此格式将主键字段序列化为Kafka消息的Key部分,用于分区路由和主键标识。 |
| value.format | 是 | String | 无 | json / csv / avro | 指定非主键字段的序列化格式。 Sink必填。Flink运行时根据此格式将非主键字段序列化为Kafka消息的Value部分。删除记录时Value序列化为NULL。 |
| sink.buffer-flush.max-rows | 否 | Integer | 无 | 正整数 | 设置Sink缓冲区最大行数。 缓冲区满后触发批量写入。增大此值可减少写入次数提高吞吐但增加延迟。仅对at-least-once和none语义生效。 |
| sink.buffer-flush.interval | 否 | Duration | 无 | 有效的持续时间,如10s,1min | 设置Sink缓冲区刷新间隔。支持 每隔此时间触发一次批量写入。与sink.buffer-flush.max-rows共同控制刷新策略,任一条件满足即触发。仅对at-least-once和none语义生效。 |
| properties.* | 否 | String | - | Kafka Producer配置 | 传递给Kafka Producer的任意配置参数,前缀为properties.。 配置项名称去掉properties.前缀后直接透传给Kafka Producer。 |
Key和Value格式参数
Upsert-Kafka连接器需要分别指定Key和Value的格式,各自有独立的格式参数,前缀分别为 key. 和 value.。
JSON格式参数(以value为例,key同理替换前缀)
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| value.json.fail-on-missing-field | 否 | Boolean | false | true / false | 控制当JSON消息中缺少DDL定义的字段时是否报错。 默认为false。设置为true时遇到缺失字段抛出异常;false时将缺失字段置为null继续处理。 |
| value.json.ignore-parse-errors | 否 | Boolean | false | true / false | 控制是否忽略JSON解析错误。 默认为false。设置为true时遇到解析错误跳过该字段而非报错,可提高容错性但可能导致数据丢失。 |
| value.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。 |
CSV格式参数(以value为例)
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| value.csv.field-delimiter | 否 | String | , | 单字符 | 指定CSV字段的分隔符。默认为逗号(,)。 |
| value.csv.ignore-parse-errors | 否 | Boolean | false | true / false | 控制是否忽略CSV解析错误。默认为false。 |
使用示例
- 示例1:从Upsert-Kafka主题消费变更日志数据,按主键自动去重合并,输出到Print结果表。
-- 创建Upsert-Kafka源表(JSON格式) CREATE TABLE upsert_kafka_order_source ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, update_time TIMESTAMP(3), PRIMARY KEY (order_id) NOT ENFORCED ) WITH ( 'connector' = 'upsert-kafka', 'topic' = 'order-changes', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'order-consumer', 'key.format' = 'json', 'value.format' = 'json' ); -- 创建Print结果表 CREATE TABLE print_sink ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, update_time TIMESTAMP(3) ) WITH ( 'connector' = 'print' ); -- 提交作业 INSERT INTO print_sink SELECT order_id, user_id, amount, status, update_time FROM upsert_kafka_order_source;
- 示例2:Key使用CSV格式,Value使用JSON格式,适用于主键字段较少的场景。
-- 创建Upsert-Kafka源表(Key=CSV,Value=JSON) CREATE TABLE upsert_kafka_mixed_source ( user_id BIGINT, user_name STRING, city STRING, member_level STRING, update_time TIMESTAMP(3), PRIMARY KEY (user_id) NOT ENFORCED ) WITH ( 'connector' = 'upsert-kafka', 'topic' = 'user-profile-changes', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'profile-consumer', 'key.format' = 'csv', 'value.format' = 'json' ); -- 创建Print结果表 CREATE TABLE print_sink ( user_id BIGINT, user_name STRING, city STRING, member_level STRING, update_time TIMESTAMP(3) ) WITH ( 'connector' = 'print' ); -- 提交作业 INSERT INTO print_sink SELECT user_id, user_name, city, member_level, update_time FROM upsert_kafka_mixed_source;
- 示例3:Upsert-Kafka端到端CDC管道,将变更数据从一个主题转发到另一个主题。
-- 上游CDC源表 CREATE TABLE upsert_kafka_cdc_source ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, PRIMARY KEY (order_id) NOT ENFORCED ) WITH ( 'connector' = 'upsert-kafka', 'topic' = 'cdc-order-changes', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'cdc-relay-consumer', 'key.format' = 'json', 'value.format' = 'json' ); -- 下游转发目标表 CREATE TABLE upsert_kafka_cdc_target ( order_id STRING, user_id BIGINT, amount DECIMAL(10, 2), status STRING, PRIMARY KEY (order_id) NOT ENFORCED ) WITH ( 'connector' = 'upsert-kafka', 'topic' = 'cdc-order-relay', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'key.format' = 'json', 'value.format' = 'json' ); -- 变更日志转发 INSERT INTO upsert_kafka_cdc_target SELECT order_id, user_id, amount, status FROM upsert_kafka_cdc_source;