# Upsert-Kafka连接器
#### 概述
Upsert-Kafka连接器是Kafka连接器的变更日志（Changelog）变体，用于以Upsert方式读写[DMS Kafka主题（Topic）](https://support.huaweicloud.com/productdesc-kafka/kafka-pd-190605001.html)。与普通Kafka连接器仅处理追加（Append）数据不同，Upsert-Kafka连接器将Kafka消息解释为变更日志记录，支持按主键的插入、更新和删除操作，适用于需要端到端Exactly-Once语义的CDC（Change Data Capture）场景。
| **类别**          | **详情**                                                                                                             |
|:---|:---|
| 支持类型          | 源表和结果表                                                                                                            |
| 运行模式           | 流模式                                                                                                                 |
| 数据格式          | 详情请参见[Formats](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/connectors/table/formats/overview/)。 |
| 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}'
);
```
![](https://support.huaweicloud.com/sqlref-flink-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
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;
  ```
  
 
