risingwavelabs/agent-skills/risingwave-best-practices

RisingWave Best Practices

14 rules covering schema design, streaming SQL patterns, sink configuration, and performance.

How to Apply

1. Read the relevant rule files for the review type below
2. Apply rules to the design or code under review
3. Explain violations with their impact and the fix

Review Procedures

Schema Review

• [ ] schema-source-vs-table.md — SOURCE vs TABLE selection
• [ ] schema-append-only.md — APPEND ONLY for immutable streams
• [ ] schema-watermark.md — Watermark placement

Materialized View Review

• [ ] mv-emit-on-window-close.md — EOWC for windowed queries
• [ ] mv-background-ddl.md — Non-blocking DDL for large tables
• [ ] mv-no-order-by.md — ORDER BY in MVs

Streaming SQL Review

• [ ] stream-tumble-windows.md — Time window functions
• [ ] stream-cdc-pattern.md — Two-step CDC setup
• [ ] stream-temporal-join.md — Joining streams with CDC tables

Sink Review

• [ ] sink-snapshot-false.md — Prevent backfill duplicates
• [ ] sink-force-compaction.md — Reduce output volume

Performance Review

• [ ] perf-shared-source.md — Shared Kafka source
• [ ] perf-indexes-on-mv.md — Indexes on materialized views
• [ ] perf-parallelism.md — MV parallelism tuning

Rule Categories

Quick Reference

Schema:

• schema-source-vs-table — CDC requires TABLE; SOURCE is for append-only streams
• schema-append-only — APPEND ONLY enables optimizations; use for immutable event data
• schema-watermark — Define watermarks at ingestion point (source/table), not in MVs

Materialized Views:

• mv-emit-on-window-close — Use EOWC for final window results; default emits partial updates
• mv-background-ddl — SET BACKGROUND_DDL=true before creating MVs over large tables
• mv-no-order-by — ORDER BY in MV applies only at creation, not to ongoing results

Streaming SQL:

• stream-tumble-windows — Use TUMBLE/HOP/SESSION, not date_trunc, for streaming windows
• stream-cdc-pattern — Two-step: CREATE SOURCE (shared) → CREATE TABLE ... FROM source
• stream-temporal-join — Join streaming source with CDC table using FOR SYSTEM_TIME AS OF

Sinks:

• sink-snapshot-false — Always use snapshot = false when adding sinks to existing MVs
• sink-force-compaction — Use force_compaction = true for high-cardinality upsert sinks

Performance:

• perf-shared-source — Multiple MVs from one Kafka topic should use shared source
• perf-indexes-on-mv — Create indexes on MV columns used in WHERE/JOIN predicates
• perf-parallelism — Increase parallelism for high-throughput MVs