risingwave-best-practices

RisingWave 最佳实践

涵盖架构设计、流式 SQL 模式、Sink 配置和性能的 14 条规则。

如何应用

1. 根据下方的评审类型，阅读相关规则文件
2. 将规则应用于待评审的设计或代码
3. 说明违规项及其影响和修复方法

评审流程

架构评审

• schema-source-vs-table.md — SOURCE 与 TABLE 的选择
• schema-append-only.md — 对不可变流使用 APPEND ONLY
• schema-watermark.md — 水印的位置

物化视图评审

• mv-emit-on-window-close.md — 对窗口查询使用 EOWC
• mv-background-ddl.md — 对大型表使用非阻塞 DDL
• mv-no-order-by.md — MV 中的 ORDER BY

流式 SQL 评审

• stream-tumble-windows.md — 时间窗口函数
• stream-cdc-pattern.md — 两步 CDC 设置
• stream-temporal-join.md — 将流与 CDC 表连接

Sink 评审

• sink-snapshot-false.md — 防止回填产生重复数据
• sink-force-compaction.md — 减少输出量

性能评审

• perf-shared-source.md — 共享 Kafka source
• perf-indexes-on-mv.md — 在物化视图上创建索引
• perf-parallelism.md — 调整 MV 并行度

规则类别

优先级	类别	影响	前缀	规则
1	架构设计	CRITICAL / HIGH	schema-	3
2	物化视图	CRITICAL / HIGH	mv-	3
3	流式 SQL	CRITICAL / HIGH	stream-	3
4	Sink 配置	HIGH / MEDIUM	sink-	2
5	性能	HIGH / MEDIUM	perf-	3

快速参考

架构：

• schema-source-vs-table — CDC 需要 TABLE；SOURCE 用于仅追加流
• schema-append-only — APPEND ONLY 可启用优化；用于不可变事件数据
• schema-watermark — 在数据摄取点（source/table）定义水印，而不是在 MV 中定义

物化视图：

• mv-emit-on-window-close — 使用 EOWC 获取最终窗口结果；默认会发出部分更新
• mv-background-ddl — 在大型表上创建 MV 之前设置 SET BACKGROUND_DDL=true
• mv-no-order-by — MV 中的 ORDER BY 仅在创建时生效，不影响后续结果

流式 SQL：

• stream-tumble-windows — 流式窗口使用 TUMBLE/HOP/SESSION，而不是 date_trunc
• stream-cdc-pattern — 两步流程：CREATE SOURCE（共享）→ CREATE TABLE ... FROM source
• stream-temporal-join — 使用 FOR SYSTEM_TIME AS OF 将流式 source 与 CDC 表连接

Sink：

• sink-snapshot-false — 向现有 MV 添加 Sink 时，始终使用 snapshot = false
• sink-force-compaction — 对高基数 upsert Sink 使用 force_compaction = true

性能：

• perf-shared-source — 从一个 Kafka topic 创建多个 MV 时应使用共享 source
• perf-indexes-on-mv — 在 WHERE/JOIN 谓词中使用的 MV 列上创建索引
• perf-parallelism — 提高高吞吐量 MV 的并行度