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

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;

相关文档