tencent cloud

Stream Compute Service

Upsert Kafka

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-09-03 10:19:45
Traduzido por IA

Introduction

The Upsert Kafka connector supports reading data from and writing data to Kafka topics in upsert mode.
As a Source, the Upsert Kafka connector produces a changelog stream, where each data record represents an update or delete event. More precisely, the value in a data record is interpreted as an UPDATE of the last value for the same key, if such a key exists. If the key does not exist, the update is considered an INSERT. By analogy with tables, data records in a changelog stream are interpreted as UPSERT, also known as INSERT/UPDATE, because any existing row with the same key is overwritten. Additionally, messages with null values are considered DELETE messages.
As a sink, the Upsert Kafka connector can consume a changelog stream. It writes INSERT/UPDATE_AFTER data as normal Kafka messages, and writes DELETE data as Kafka messages with null values (which indicates the messages corresponding to the key will be deleted). Flink guarantees the message ordering on the primary key by partitioning data based on the values of the primary key columns, so the UPDATE/DELETE messages on the same key fall into the same partition.

Version Description

Flink Version
Description
1.13
Supported. Based on community version 1.13, with Kafka client version 2.4.1.
1.14
Supported. Based on community edition 1.14, with Kafka client version 2.4.1.
1.16
Supported. Based on community edition 1.16, with Kafka client version 3.2.3.
1.18
Supported. Based on community edition 3.2.0, with Kafka client version 3.4.0.
1.20
Supported. Based on community edition 3.3.0, with Kafka client version 3.4.0.
Note:
Starting from Flink 1.17, the community has split Kafka Connector into a separate repository for maintenance and adopted a new version numbering scheme.

DDL Definition

CREATE TABLE kafka_upsert_sink_table (
id INT,
name STRING,
PRIMARY KEY (id) NOT ENFORCED
) WITH (
-- Define Upsert Kafka parameters.
'connector' = 'upsert-kafka', -- Specify the connector.
'topic' = 'topic', -- Replace this with the topic you want to write to.
'properties.bootstrap.servers' = '...', -- Replace this with your Kafka connection address.
'key.format' = 'json', -- Define the data format of keys.
'value.format' = 'json' -- Define the data format of values.
);
Note:
Make sure you define the primary key in the DDL.

WITH Parameters

Parameter
Required or Not
Default Value
Data Type
Description
connector
Required
(none)
String
Specifies the connector to use. For Upsert Kafka connectors, use: 'upsert-kafka'.
topic
Required
(none)
String
The name of the Kafka topic to read from and write to.
properties.bootstrap.servers
Required
(none)
String
The list of Kafka brokers, separated with commas.
properties.*
Optional
(none)
String
Any Kafka configurations. Its suffixes should match the parameter name defined in Kafka 4.1 Documentation.
Flink automatically removes the "properties." prefix from option names and passes the transformed key names and values to KafkaClient. For example, you can disable automatic topic creation by setting 'properties.allow.auto.create.topics' = 'false'. However, certain options, such as 'key.deserializer' and 'value.deserializer', cannot be passed in this way because Flink rewrites the values of these parameters.
key.format
Required
(none)
String
The format used to serialize and deserialize the key part of Kafka messages. The key fields are specified by the PRIMARY KEY syntax. Supported formats include 'csv', 'json', and 'avro'. Note that the avro format requires the dependent flink-avro jar to be uploaded, while other formats do not require an upload.
key.fields-prefix
optional
(none)
String
Defines a custom prefix for all fields in 'key.fields' to avoid name conflicts with fields in 'value.fields'. By default, the prefix is empty. If a custom prefix is defined, the table schema and 'key.fields' will use the prefixed names. When the data type for the 'key.fields' format is constructed, the prefix will be removed and the non-prefixed names in the key format will be used. Note that this option requires 'value.fields-include' to be set to 'EXCEPT_KEY'.
value.format
Required
(none)
String
The format used to serialize and deserialize the value part of Kafka messages. Supported formats include 'csv', 'json', and 'avro'. Note that the avro format requires the dependent flink-avro jar to be uploaded, while other formats do not require an upload.
value.fields-include
Optional
'ALL'
String
A policy specifying how to deal with key columns in the data type of the value format. Valid values:
ALL: All physical columns of the table schema will be included in the value format, including columns defined as primary keys.
EXCEPT_KEY: All physical columns of the table schema will be included in the value format, except columns defined as primary keys.
sink.parallelism
Optional
(none)
Integer
Defines the parallelism of the upsert-kafka sink operator. By default, the framework determines the parallelism, which is kept consistent with the parallelism of the upstream chained operator.
sink.buffer-flush.max-rows
Optional
0
Integer
The maximum number of records that can be cached before a flush. When the sink receives many updates on the same key, the buffer retains the last record for that key. Therefore, the sink buffer helps reduce the amount of data sent to the Kafka topic and avoids sending potential tombstone messages. It can be disabled by setting it to '0'. By default, this option is not enabled. Note that to enable the sink buffer, you must set both 'sink.buffer-flush.max-rows' and 'sink.buffer-flush.interval' to values greater than zero.
sink.buffer-flush.interval
Optional
0
Duration
The interval at which asynchronous threads flush data. When the sink receives many updates on the same key, the buffer will retain the last record of the same key. This helps reduce the amount of data to be sent to Kafka topic and avoid sending potential tombstone messages.
It can be disabled by setting it to '0'. By default, this option is not enabled. Note that to enable the sink buffer, you must set both 'sink.buffer-flush.max-rows' and 'sink.buffer-flush.interval' to values greater than zero.

Sample Code

CREATE TABLE `kafka_json_source_table` (
`id` INT,
`name` STRING
) WITH (
-- Define Kafka parameters.
'connector' = 'kafka',
'topic' = 'Data-Input', -- Replace this with the topic you want to consume data from.
'scan.startup.mode' = 'latest-offset', -- Valid values include latest-offset, earliest-offset, specific-offsets, group-offsets, and timestamp.
'properties.bootstrap.servers' = '172.28.28.13:9092', -- Replace this with your Kafka connection address.
'properties.group.id' = 'testGroup', -- (Required) The group ID.

-- Define the data format (JSON).
'format' = 'json',
'json.fail-on-missing-field' = 'false', -- If this is 'false', no errors will occur even when parameters are missing.
'json.ignore-parse-errors' = 'true' -- If this is 'true', all parse errors will be ignored.
);

CREATE TABLE kafka_upsert_sink_table (
id INT,
name STRING,
PRIMARY KEY (id) NOT ENFORCED
) WITH (
-- Define Upsert Kafka parameters.
'connector' = 'upsert-kafka', -- Specify the connector.
'topic' = 'topic', -- Replace this with the topic you want to consume data from.
'properties.bootstrap.servers' = '...', -- Replace this with your Kafka connection address.
'key.format' = 'json', -- Define the data format of keys.
'value.format' = 'json' -- Define the data format of values.
);

-- Calculate pv and uv and insert them to upsert-kafka sink.
INSERT INTO kafka_upsert_sink_table
SELECT * FROM kafka_json_source_table;

SASL authentication

SASL/PLAIN username and password authentication

1. Refer to Message Queue CKafka - Configure ACL Policy to configure the SASL_PLAINTEXT authentication method for Topic access using username and password.
2. Refer to Message Queue CKafka - Add Routing Policy, select the SASL_PLAINTEXT access method, and access the Topic using the network address under this access method.
3. Configure WITH parameters for the job.
CREATE TABLE `YourTable` (
...
) WITH (
...
'properties.sasl.jaas.config' = 'org.apache.kafka.common.security.plain.PlainLoginModule required username="ckafka-xxxxxxxx#YourUserName" password="YourPassword";',
'properties.security.protocol' = 'SASL_PLAINTEXT',
'properties.sasl.mechanism' = 'PLAIN',
...
);
Note:
username is Instance ID + # + the username just configured, and password is the user password just configured.

SASL/GSSAPI Kerberos authentication

Tencent Cloud CKafka does not currently support Kerberos authentication. If your self-built Kafka has Kerberos authentication enabled, you can refer to the following steps to configure the job.
1. Obtain the Kerberos configuration files for your self-built Kafka cluster. If you built it based on a Tencent Cloud EMR cluster, obtain the krb5.conf and emr.keytab files. The paths are as follows.
/etc/krb5.conf
/var/krb5kdc/emr.keytab
2. Package the files obtained in step 1 into a jar package.
jar cvf kafka-xxx.jar krb5.conf emr.keytab
3. Check the JAR structure (run the vim command vim kafka-xxx.jar). The JAR file includes the following information. Make sure no file is missing and the structure is correct.
META-INF/
META-INF/MANIFEST.MF
emr.keytab
krb5.conf
4. Upload the jar package on the Package Management page and reference this package in the job parameter configuration.
5. Obtain the kerberos principal for configuring the job's Advanced Parameters.
klist -kt /var/krb5kdc/emr.keytab

# The output is as follows. Select the first one: hadoop/172.28.28.51@EMR-OQPO48B9
KVNO Timestamp Principal
---- ------------------- ------------------------------------------------------
2 08/09/2021 15:34:40 hadoop/172.28.28.51@EMR-OQPO48B9
2 08/09/2021 15:34:40 HTTP/172.28.28.51@EMR-OQPO48B9
2 08/09/2021 15:34:40 hadoop/VM-28-51-centos@EMR-OQPO48B9
2 08/09/2021 15:34:40 HTTP/VM-28-51-centos@EMR-OQPO48B9
6. Configure WITH parameters for the job.
CREATE TABLE `YourTable` (
...
) WITH (
...
'properties.security.protocol' = 'SASL_PLAINTEXT',
'properties.sasl.mechanism' = 'GSSAPI',
'properties.sasl.kerberos.service.name' = 'hadoop',
...
);
Note:
The value of the parameter properties.sasl.kerberos.service.name must match the principal you selected. If you selected hadoop/${IP}@EMR-OQPO48B9, set the value to hadoop.
7. Configure the job's Advanced Parameters.
security.kerberos.login.principal: hadoop/172.28.2.13@EMR-4K3VR5FD
security.kerberos.login.keytab: emr.keytab
security.kerberos.login.conf: krb5.conf
security.kerberos.login.contexts: KafkaClient
fs.hdfs.hadoop.security.authentication: kerberos

Ajuda e Suporte

Esta página foi útil?

comentários