RisingWave 到 Apache Pinot:基于 Kafka UPSERT Sink 的实时订单流同步实践

原创2026-09-24 13:11:51603 阅读
文章标签:数据库流处理后端数据工程

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 教学项目改造而来。整体数据链路为:

  1. RisingWave 中创建带主键的 orders 表;
  2. 通过 CREATE SINK 将表数据以 UPSERT ENCODE JSON 格式写入 Kafka topic orders.upsert.log;
  3. Apache Pinot 集群(1 个 Controller、1 个 Broker、1 个 Server)通过 Kafka 低阶消费(lowLevel consumer)读取该 topic,将数据写入名为 orders 的 REALTIME 表;
  4. 在 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。

延伸阅读

登录后查看全文
risingwave