Case Studies Overview

# StreamSQL Case Studies

This chapter presents StreamSQL applied to real-world business scenarios, covering common stream-processing needs such as data merging, change data capture, and real-time analysis. Every case is built on the StreamSQL source code, so it is runnable and practical.

# Case Categories

All cases are IoT scenarios; the SQL has been run and verified, with inputs and outputs provided. See How to Run Case SQL below for how to run them.

# 🔧 Data Processing

Data Filtering and Transformation - Non-aggregation: filter, arithmetic conversion, CASE grading (EmitSync)
Stream-Table JOIN Metadata Enrichment - Enrich device readings with location/model attributes from a dimension table

# ⏱️ Windowed Aggregation

Sliding Window and Continuous Detection - SlidingWindow + HAVING for "above threshold for N consecutive seconds"
Session Window and Device Online Status - SessionWindow splits online sessions by activity gap
IoT Temperature Alerting and Metrics Aggregation - Overview of single-point alert / tumbling / counting / trigger / global window modes

# 🔄 Change Data Capture

Change Data Capture - Analytic functions (lag/had_changed/changed_cols) for instantaneous change detection

# What Each Case Contains

Each case focuses on scenario + SQL + input/output, without repeating the Go boilerplate:

Business Scenario - Requirement background and analysis
SQL - The complete StreamSQL query
Input / Output - Simulated data and actual run results
Behavior Notes - Key semantics and pitfalls

How to run these SQL queries

All cases share the same boilerplate; see How to Run Case SQL below.

# How to Run Case SQL

Each case shows only the SQL plus its inputs and outputs. To actually run it, use the unified Go boilerplate below — paste the case SQL into the sql variable and feed data as described in the case.

go get github.com/rulego/streamsql

package main

import (
	"fmt"
	"time"

	"github.com/rulego/streamsql"
)

func main() {
	ssql := streamsql.New()
	defer ssql.Stop()

	// ① Paste the case SQL here
	sql := `SELECT deviceId, temperature FROM stream WHERE temperature > 30`
	if err := ssql.Execute(sql); err != nil {
		panic(err)
	}

	// ② Pick one of two options, depending on whether the case is "non-aggregation" or "aggregation/window"

	// Option A: non-aggregation queries (no GROUP BY/window) use EmitSync for a synchronous single-row result
	// result, err := ssql.EmitSync(map[string]any{"deviceId": "d1", "temperature": 32.0})
	// fmt.Println(result)

	// Option B: aggregation / window queries use Emit + AddSink for a batch callback when the window closes
	ssql.AddSink(func(batch []map[string]any) {
		for _, row := range batch {
			fmt.Printf("%+v\n", row)
		}
	})
	ssql.Emit(map[string]any{"deviceId": "d1", "temperature": 32.0})

	time.Sleep(500 * time.Millisecond) // let the async sink drain
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

Pick the API by query type:

Query type	What to use	Notes
Non-aggregation (filter/transform/analytic function)	`EmitSync(data)`	Synchronously returns a single row; returns `nil` if WHERE is not matched
Aggregation / window / global window	`Emit(data)` + `AddSink(...)`	Batch callback when the window closes

Skip the sleep when testing time windows

When writing tests or just wanting to see time-window output immediately, call ssql.TriggerWindow() to flush the window at once instead of time.Sleep-ing until the window expires. See IoT Temperature Alerting · Scenario D.

# Case Features

✅ Based on real source code - Every case is built on actual StreamSQL features
✅ SQL is paste-and-run - Just use the unified boilerplate above
✅ Business-oriented - Geared toward real scenarios with practical value
✅ Progressive - From simple to complex, easy to learn and understand
✅ Best practices - Shows the recommended way to use StreamSQL

StreamSQL Quick Start - Basic getting-started tutorial
SQL Reference Manual - Complete SQL syntax reference
API Reference - Detailed API documentation

# 💡 Contributing Cases

If you have a good StreamSQL use case, contributions are welcome:

Fork the StreamSQL project (opens new window)
Add your case under the examples/ directory
Submit a Pull Request
We will add outstanding cases to the docs

Let's start exploring the power of StreamSQL, and learn how to use it effectively in production through these real-world cases!

Edit this page on GitHub

Last Updated: 2026/07/11, 04:40:00

← Custom Functions Stream-Table JOIN Metadata Enrichment→