RisingWave 到 Apache Pinot:基于 Kafka UPSERT Sink 的实时订单流同步实践
RisingWave 到 Apache Pinot:基于 Kafka UPSERT Sink 的实时订单流同步实践
RisingWave 是流式数据库,本指南讲解如何将 RisingWave 中的带主键业务表(以订单表为例)通过 Kafka 连接器以 UPSERT + JSON 格式持续写入 Apache Pinot,使 Pinot 中的实时表随 RisingWave 的插入与更新自动同步。阅读完本文,你将掌握完整的端到端搭建步骤、Pinot 实时表与 Kafka 流式解码的配置方法,以及如何验证更新(UPDATE)能正确反映到 Pinot 查询结果中。
场景与整体架构
本文对应的完整示例位于仓库的 integration_tests/pinot-sink 目录,演示由 pinot-upsert 教学项目改造而来。整体数据链路为:
- RisingWave 中创建带主键的
orders表; - 通过
CREATE SINK将表数据以UPSERT ENCODE JSON格式写入 Kafka topicorders.upsert.log; - Apache Pinot 集群(1 个 Controller、1 个 Broker、1 个 Server)通过 Kafka 低阶消费(lowLevel consumer)读取该 topic,将数据写入名为
orders的 REALTIME 表; - 在 RisingWave 中执行
INSERT与UPDATE,随后用 Pinot 的 SQL 查询接口验证数据已同步且更新已生效。
启动集群:Docker Compose 一次拉起 RisingWave 与 Pinot
示例根目录的 docker-compose.yml 定义了完整环境,执行:
docker compose up -d
集群由以下服务组成:
- risingwave-standalone、postgres-0、grafana-0、minio-0、prometheus-0:通过
extends复用仓库根目录 docker/docker-compose.yml 中定义的 RisingWave 单机组件(元数据存储于 SQLite、对象存储使用 MinIO,前端监听 4566 端口); - kafka:
confluentinc/cp-kafka,单节点 KRaft 模式(KAFKA_PROCESS_ROLES 为broker,controller),内部监听kafka:9092,同时暴露宿主机端口29092供外部调试; - zookeeper:
zookeeper:3.8,供 Pinot 集群使用(端口 2181); - pinot-controller:
apachepinot/pinot:latest,启动参数StartController -zkAddress zookeeper:2181,并把本目录./config挂载到容器内/config(端口 9000); - pinot-broker:
StartBroker -zkAddress zookeeper:2181(端口 8099); - pinot-server:
StartServer -zkAddress zookeeper:2181; - postgres:仅作为执行更新 SQL 的便利容器(挂载 update.sql)。
三步准备:Kafka Topic、RisingWave 表与 Sink、Pinot 实时表
1. 创建 Kafka Topic
在 Kafka 容器内创建主题 orders.upsert.log:
docker compose exec kafka \
kafka-topics --create --topic orders.upsert.log --bootstrap-server kafka:9092
该主题将承载 RisingWave Sink 发出的每一条 upsert 事件,也是 Pinot 实时表的流式数据源。
2. 在 RisingWave 中创建表与 UPSERT Sink
连接 RisingWave 前端(psql 客户端,默认端口 4566):
psql -h localhost -p 4566 -d dev -U root
在 psql 客户端内依次执行:
CREATE TABLE IF NOT EXISTS orders
(
id INT PRIMARY KEY,
user_id BIGINT,
product_id BIGINT,
status VARCHAR,
quantity INT,
total FLOAT,
created_at BIGINT,
updated_at BIGINT
);
然后创建 Kafka sink:
CREATE SINK orders_sink FROM orders WITH (
connector = 'kafka',
properties.bootstrap.server = 'kafka:9092',
topic = 'orders.upsert.log',
primary_key = 'id'
) FORMAT UPSERT ENCODE JSON;
两条语句的等价脚本分别见 create_source.sql 与 create_sink.sql。
关于 primary_key 的说明:FORMAT UPSERT 要求指定 primary_key(即下游主键),用于决定 Kafka 消息键(message key)以及同一键的更新/删除语义。在 RisingWave 源码 src/connector/src/sink/kafka.rs 中,upsert Kafka sink 会解析 primary_key 为一个字段索引向量;若未定义该字段,创建 sink 时会直接报错 primary key not defined for kafka sink (please define in 'primary_key' field)(见 kafka.rs)。因此示例中 primary_key = 'id' 与表的主键、以及后续 Pinot schema 的主键列必须保持一致。
3. 在 Pinot 中创建实时表 orders
Pinot 的表与 schema 配置已放在 config/orders_schema.json 和 config/orders_table.json,通过 Controller 的 Admin 工具注册:
docker exec -it pinot-controller /opt/pinot/bin/pinot-admin.sh AddTable \
-tableConfigFile /config/orders_table.json \
-schemaFile /config/orders_schema.json -exec
Schema 要点
orders_schema.json 定义了与 RisingWave 表列一一对应的字段:
primaryKeyColumns:["id"],与 RisingWave sink 的primary_key = 'id'对齐;dimensionFieldSpecs:id(INT)、user_id(INT)、product_id(INT)、status(STRING);metricFieldSpecs:quantity(INT)、total(FLOAT);dateTimeFieldSpecs:updated_at(LONG),时间格式1:MILLISECONDS:EPOCH、粒度1:MILLISECONDS,作为时间列驱动数据保留与 segment 切分。
注意一个值得留意的细节:RisingWave 表中 user_id、product_id 是 BIGINT,而 Pinot schema 中声明为 INT。从源码结构看,Kafka JSON 解码器按 schema 类型解析数值字段,示例数据取值较小(10、100),因此不会溢出。生产环境中若数值可能超过 32 位整数范围,应按实际范围把 Pinot 侧字段类型调整为 LONG,避免精度丢失。
表配置要点
orders_table.json 中与 Kafka 流式消费直接相关的配置:
tableType:REALTIME,数据直接从 Kafka 实时消费;streamConfigs.streamType:kafka,topic 为orders.upsert.log;stream.kafka.decoder.class.name:org.apache.pinot.plugin.stream.kafka.KafkaJSONMessageDecoder,按 JSON 解析消息;stream.kafka.consumer.type:lowLevel,使用低阶消费者;stream.kafka.consumer.factory.class.name:org.apache.pinot.plugin.stream.kafka20.KafkaConsumerFactory;stream.kafka.broker.list:kafka:9092,stream.kafka.hlc.zk.connect.string/stream.kafka.zk.broker.url:zookeeper:2181/kafka;realtime.segment.flush.threshold.size与realtime.segment.flush.threshold.rows:均为 30,即累计 30 行(或达到阈值大小)后触发 segment 落盘,保证小数据量 demo 也能尽快可见;upsertConfig.mode:FULL,启用 Pinot 侧按主键id去重更新,这是让 UPDATE 语义生效的关键;segmentsConfig:timeColumnName: updated_at、retentionTimeUnit: DAYS、retentionTimeValue: 1(保留 1 天)、segmentPushType: APPEND。
插入数据并验证同步
插入三条订单
在 psql 客户端执行:
insert into orders values (1, 10, 100, 'INIT', 1, 1.0, 1685421033000, 1685421033000);
insert into orders values (2, 10, 100, 'INIT', 1, 1.0, 1685421033000, 1685421033000);
insert into orders values (3, 10, 100, 'INIT', 1, 1.0, 1685421033000, 1685421033000);
flush;
用 Pinot CLI 查询:
docker compose exec pinot-controller \
/opt/pinot/bin/pinot-admin.sh PostQuery -brokerHost \
pinot-broker -brokerPort 8099 -query "SELECT * FROM orders"
预期结果(字段顺序按 Pinot 内部列序返回,与 schema 声明顺序不一定完全一致):
{
"rows": [
[1, 100, 1, "INIT", 1.0, 1685421033000, 10],
[2, 100, 1, "INIT", 1.0, 1685421033000, 10],
[3, 100, 1, "INIT", 1.0, 1685421033000, 10]
]
}
更新一条数据并再次验证
将 id = 1 的订单状态更新为 PROCESSING:
UPDATE orders
SET status = 'PROCESSING',
updated_at = updated_at + 1000
WHERE id = 1;
flush;
再次执行同样的 Pinot 查询,预期结果中 id = 1 的行变为 "PROCESSING" 且 updated_at 变为 1685421034000,同时 id = 2、3 保持不变:
{
"rows": [
[2, 100, 1, "INIT", 1.0, 1685421033000, 10],
[3, 100, 1, "INIT", 1.0, 1685421033000, 10],
[1, 100, 1, "PROCESSING", 1.0, 1685421034000, 10]
]
}
这一步验证了完整链路:RisingWave 对表的 UPDATE 通过 Kafka upsert 消息送达 Pinot,并由 Pinot 的 upsertConfig 按主键 id 覆盖旧记录。
Kafka 中的 UPSERT Payload 格式
整个 demo 会在 topic orders.upsert.log 中产生 4 条 upsert 事件,JSON 载荷如下:
{"created_at":1685421033000,"id":1,"product_id":100,"quantity":1,"status":"INIT","total":1.0,"updated_at":1685421033000,"user_id":10}
{"created_at":1685421033000,"id":2,"product_id":100,"quantity":1,"status":"INIT","total":1.0,"updated_at":1685421033000,"user_id":10}
{"created_at":1685421033000,"id":3,"product_id":100,"quantity":1,"status":"INIT","total":1.0,"updated_at":1685421033000,"user_id":10}
{"created_at":1685421033000,"id":1,"product_id":100,"quantity":1,"status":"PROCESSING","total":1.0,"updated_at":1685421034000,"user_id":10}
其中前三条对应三次 INSERT,第四条对应 id = 1 的 UPDATE。这也是 Pinot KafkaJSONMessageDecoder 与 upsertConfig 消费的数据形态。
自动化验证:CI 与检查脚本如何确保正确性
该示例不仅可手动跑通,还以 pinot-sink 的身份接入仓库 CI 的集成测试体系(见 ci/scripts/gen-integration-test-yaml.py,其测试标识为 pinot-sink: ["json"])。
- prepare.sh 是 CI 中实际使用的初始化脚本:它会轮询等待 Kafka 容器运行并就绪(用
kafka-topics --list探测 broker 是否真正接受连接),然后创建 topic;随后等待pinot-controller就绪并通过pinot-admin.sh AddTable注册表与 schema。脚本中特意不使用-it(CI 无 TTY),所有命令均通过docker compose exec -T/docker exec执行。 - sink_check.py 是数据校验脚本:先对 Pinot broker 的
POST http://localhost:8099/query/sql接口执行SELECT COUNT(*) FROM orders确认有数据落表;然后通过 postgres 容器执行 update.sql(即对id = 1执行 UPDATE 并FLUSH);最后轮询查询SELECT status, updated_at FROM orders WHERE id = 1 ORDER BY updated_at DESC LIMIT 1,直到状态变为PROCESSING,否则判定失败并退出码 1。
排查与调优提示
- 查询不到数据:先确认 Kafka topic 已创建、sink 已成功
CREATE_SINK(psql 返回CREATE_SINK),再确认 Pinot 表已注册成功;同时检查realtime.segment.flush.threshold.*,若阈值过高而数据量少,segment 迟迟不落盘会导致查询可见性延迟,本示例设置为 30。 - UPDATE 不生效:Pinot 表配置必须开启
upsertConfig.mode = "FULL",且 RisingWave sink 的primary_key、表主键、Pinot schema 的primaryKeyColumns三者要一致。 - 类型精度:RisingWave 的 BIGINT 列若在 Pinot schema 中声明为 INT,需确认业务数值不会超出 32 位整数范围,必要时把 Pinot 侧字段改为 LONG。
- 端口与监听:Broker 查询端口为 8099(容器内
pinot-broker),Controller 管理端口为 9000,Kafka 对外调试端口为 29092;RisingWave 前端为 4566。
延伸阅读
- 在仓库 src/connector/src/sink/kafka.rs 中查看 Kafka sink 对
primary_key的解析与校验实现; - 在 src/connector/src/sink/formatter/mod.rs 中查看关于 append-only(无
primary_key/downstream_pk)与 upsert 输出格式的说明; - 参考 docker/docker-compose.yml 了解 RisingWave 单机各组件(meta、compute、frontend、MinIO、Grafana、Prometheus)的默认配置;
- 更多 sink 集成示例参见 integration_tests/README.md 与 integration_tests 下的
*-sink目录(如 kafka、pulsar、clickhouse 等)。