首个稳定版本（Stable Release）。 从 0.x 迈入 1.0.0，核心 API 与行为契约正式锁定，后续按语义化版本演进，可用于生产环境。

从 v0.10.2 到 v1.0.0，历经 115 个提交、5 个中间版本。这一版补齐了流-表 JOIN、事件时间水位线、全局窗口等核心能力，并系统性修复了一批会导致崩溃或静默丢数据的缺陷。

这版到底带来了什么

一句话：一个用纯 Go 写、零外部依赖、能在树莓派上跑、语法和 Flink SQL 几乎一致的边缘流处理引擎，终于补齐了它最缺的几块拼图。

如果你没时间细看，记住这四件事就够了：

1. 流-表 JOIN——流数据现在能关联维度表（设备元信息、车型库、用户档案……），而且是真 JOIN，支持 INNER/LEFT、复合键、多表，富化结果还能继续聚合。

2. 事件时间 + Watermark 真正可用——乱序、迟到、空数据源，这些流处理的"老大难"现在有了对齐 Flink 的水位线机制，而且不会再被一条脏数据毒死。

3. 全局窗口（GlobalWindow）+ TRIGGER WHEN——不依赖时间的阈值驱动告警，"累计满 1000 条发一次"、"最高温破 50 报警"这类需求原生支持。

4. 可观测性 + 性能——新增 metrics 包和按实例的结构化日志；表达式求值路径提速数百倍；一大批会导致崩溃或静默丢数据的 bug 被连根拔起。

下面分三部分讲：这次的重点更新怎么用、能解决什么问题；StreamSQL 是什么、适合谁；以及从 v0.10.2 起的完整变更清单。

---

一、本次重点更新解读与应用场景

1. 流-表 JOIN：让流"认识"维度表

解决什么问题：流数据天生是"窄"的——传感器上报的往往只有 deviceId、temperature 这些裸值。但业务真正想分析的是"哪个工厂、哪条产线、什么型号的设备温度超标"。工厂、产线、型号这些维度信息存在静态表里，不会随每条数据重复发送。JOIN 就是把它们"贴"到流上的胶水。

这是 IoT 场景里最高频的需求之一，也是 v1.0.0 最重磅的特性。

怎么写：

ssql := streamsql.New()
defer ssql.Stop()

// 1) SQL：把维度表 m 关联到流上，再按"工厂 + 型号"做 1 分钟滚动聚合
sql := `SELECT m.location, m.model,
               AVG(temperature) AS avg_temp,
               COUNT(*)         AS samples
        FROM stream
        JOIN devices m ON deviceId = m.deviceId
        GROUP BY m.location, m.model, TumblingWindow('1m')`
ssql.Execute(sql)

// 2) 注册维度表：键自动从 ON 子句推导，无需重复声明
ssql.RegisterTable("devices", []map[string]any{
    {"deviceId": "d1", "location": "plant-A", "model": "X100"},
    {"deviceId": "d2", "location": "plant-B", "model": "X200"},
})

ssql.AddSink(func(results []map[string]any) { fmt.Printf("%v\n", results) })

// 3) 投放原始数据——注意：流里只有 deviceId 和温度，没有工厂/型号
ssql.Emit(map[string]any{"deviceId": "d1", "temperature": 40.0})
ssql.Emit(map[string]any{"deviceId": "d1", "temperature": 44.0})
ssql.Emit(map[string]any{"deviceId": "d2", "temperature": 35.0})

窗口触发后，每条流数据已自动"贴"上维度表字段，输出长这样：

[
  {location: plant-A, model: X100, avg_temp: 42.0, samples: 2},  // ← d1 的两条，工厂/型号来自维度表
  {location: plant-B, model: X200, avg_temp: 35.0, samples: 1},  // ← d2 的一条
]

关键就在这里：你投进去的是裸的 {deviceId, temperature}，吐出来的是带工厂、型号、聚合值的完整业务记录——维度信息是 JOIN 当场贴上去的，流数据本身从不重复携带。

三个值得说的设计：

• 富化在过滤之前。所以 WHERE m.location = 'plant-A' 能直接按维度表字段筛数据，LEFT JOIN 没匹配上时 WHERE m.location IS NULL 还能挑出"找不到元信息的孤儿设备"。

• 键自动推导。RegisterTable("devices", rows) 不传键，引擎自己从 ON deviceId = m.deviceId 里推出表侧字段是 deviceId。复合键（ON a=m.a AND b=m.b）也自动推。想覆盖就显式传：RegisterTable("devices", rows, "deviceId")。

• 不止内存表。内置 MemoryTableSource，但你也可以实现 TableSource 接口（Name/Lookup/Init/Close）接数据库、Redis、HTTP、文件——刷新策略你自己定，引擎每条流数据来都走一次 Lookup。

典型场景：工厂 1000 台设备每秒 10 万条原始数据，边缘端 JOIN 上设备台账后，按"产线 + 型号"聚合出每分钟关键指标，只把 MB 级结果回传云端。

2. 事件时间 + Watermark：正经的乱序处理

解决什么问题：处理时间（数据到达系统的时刻）简单粗暴，但只要数据晚到或乱序，结果就错。事件时间（数据自己带的时间戳）才准，但它要处理三个麻烦：乱序、迟到、以及一条 2099-01-01 的脏数据把水位线永久顶到天上去。

v1.0.0 把这一整套机制做扎实了，语义对齐 Flink。

SELECT deviceId, COUNT(*) AS cnt, window_start() AS w_start
FROM stream
GROUP BY deviceId, TumblingWindow('1m')
WITH (
    TIMESTAMP='eventTime',     -- 事件时间字段
    TIMEUNIT='ms',             -- 单位码：dd/hh/mi/ss/ms/ns（毫秒时间戳用 ms；注意 's' 无效，会静默回退成 ms）
    MAXOUTOFORDERNESS='5s',    -- 容忍 5 秒乱序
    ALLOWEDLATENESS='2s',      -- 窗口触发后还能再吃 2 秒迟到数据，补发结果
    IDLETIMEOUT='10s'          -- 10 秒没数据就按处理时间推进水位线，防止窗口永不关闭
)

这版专门修的坑（之前是定时炸弹）：

• 数值时间戳终于能用了。之前 JSON 解出来的 float64 毫秒时间戳被全量静默丢弃——也就是说你写 TIMESTAMP='ts'，数据却一条都没进窗口，而且不报错。现在 int/int64/float64/数值字符串都认。

• 水位线防毒化。一条远未来时间戳（年份 2099 的垃圾数据）以前会把水位线永久顶高，导致所有真实事件全被判成迟到丢弃。现在封顶在 now + 容忍度 + 24h，正常数据绝不受影响。

• Session 事件时间死锁、水位线丢包、迟到更新漏事件——三个会导致"数据流卡死"或"窗口永不触发"的硬 bug 全部修复。

3. 全局窗口 + TRIGGER WHEN：阈值驱动，不靠时间

解决什么问题：滚动窗口是"每 1 分钟统计一次"。但有一类需求跟时间无关："某设备累计够 1000 个事件就输出一次统计然后清零"、"一组里的最高温破 50 就报警"。这种"满 N 触发"的语义，之前要拿时间窗口硬凑，很别扭。

v1.0.0 引入 GlobalWindow，对齐 Flink 的 GlobalWindows：

SELECT deviceId, AVG(temperature) AS avg_t, COUNT(*) AS cnt
FROM stream
GROUP BY deviceId, GLOBAL WINDOW TRIGGER WHEN COUNT(*) >= 1000
-- 每个设备攒够 1000 条：输出当前聚合结果，然后该组状态清零，下一批从 0 开始

TRIGGER WHEN 是谓词，复合条件（COUNT(*) >= 1000 AND MAX(temperature) > 80）也行。不写 TRIGGER WHEN 的全局窗口会在解析期直接拒绝——因为它永远不会输出，这是配置错误不是性能问题。

4. 可观测性：metrics + 结构化日志

之前要看引擎内部状态只能 fmt.Println。v1.0.0 新增了 metrics 包（Counter/Gauge/Histogram/Registry，全原子无锁）和按实例的结构化日志（Field 类型、Text/JSON 双格式）。

// 直接拿 registry 看输入/输出/丢弃计数
reg := ssql.Metrics()
fmt.Println(reg.GetCounter("input").Value())

// 每个实例一个 logger，不再全局串扰（多实例并存时尤其重要）
ssql := streamsql.New(
    streamsql.WithSchema(mySchema),
    streamsql.WithLogger(myStructuredLogger),
)

配套的 WithSchema 是 opt-in 的输入校验：声明字段类型/必填/默认值，Emit 进来的脏数据会被校验、丢弃并计数。不配就零开销，配了就帮你挡掉"temperature 字段是个字符串"这类低级问题。

5. 性能：表达式求值提速数百倍

这是 v1.0.0 里最"隐形"但最值钱的工作。StreamSQL 的 WHERE 过滤和 SELECT 计算都要先把表达式解析、编译再求值，之前每行数据都重新编译一遍、重建函数包装，热点路径开销惊人。

优化后的对比（同一台机器、同一批基准）：

场景	优化前	优化后	提速
表达式桥接（算术）	343µs / 1398 alloc	594ns / 4 alloc	577×
字段读取	330µs / 1374 alloc	266ns / 1 alloc	1240×
主路径 SELECT 含计算表达式	745µs / 2814 alloc	2.5µs / 12 alloc	298×
WHERE 单字段比较	216ns / 1 alloc	35ns / 0 alloc	6.2×（零分配）

手段是工程化的三连击：缓存编译后的表达式避免重复解析、精简求值环境省去每行重建的函数包装、给常见的 WHERE 模式（字段 OP 字面量、扁平 AND/OR）加绕过反射的直接读取快速路径。快速路径有逐行结果比对测试兜底，语义和完整求值完全一致，不匹配就自动回退。

---

二、StreamSQL 是什么（特点、优势、示例）

一句话定位

StreamSQL 是一个专为物联网边缘场景设计的轻量级流处理引擎——用你早就熟悉的 SQL 语法，处理源源不断、永不停止的数据流。

它要填的空档很明确。传统流处理你只有两个极端选择：

• 时序数据库（InfluxDB、TimescaleDB）——存储强，但实时计算弱，复杂聚合性能差；

• 重型分布式框架（Flink、Storm）——功能强，但部署重、吃资源，边缘设备根本扛不住。

StreamSQL 是第三条路：纯 Go、零外部依赖、秒级启动、纯内存计算，专门为"资源受限的边缘端做实时聚合"而生。

核心架构

        SQL 字符串
           │
           ▼
   ┌───────────────┐    ┌──────────────┐    ┌────────────────┐
   │  rsql 解析器  │ →  │  stream 处理 │ →  │  window 窗口   │
   │  SQL → AST    │    │  富化/过滤    │    │  聚合/触发      │
   └───────────────┘    └──────────────┘    └────────────────┘
                                                     │
   ┌───────────────┐    ┌──────────────┐             ▼
   │  functions    │    │  expr 表达式 │      结果 → Sinks
   │  60+ 内置函数 │    │  引擎        │      (回调/channel/打印)
   └───────────────┘    └──────────────┘

• SQL 解析器（rsql）：把标准 SQL 解析成 AST，搭出处理管道。

• 流处理器（stream）：富化（JOIN）、过滤（WHERE）、转换，含缓冲与溢出策略。

• 窗口管理器（window）：滚动 / 滑动 / 会话 / 计数 / 全局，覆盖窗口生命周期。

• 函数系统（functions）：60+ 内置函数，8 种类型，支持插件式自定义。

• 表达式引擎（expr）：算术、逻辑、字段引用，经过 v1.0.0 的性能重写。

设计理念

• 轻量级优先：纯 Go、近乎零外部依赖，内存高效，秒级启动。

• SQL 优先：声明式，业务逻辑直白，学习成本极低——会写 SQL 就会用。

• 可观测优先：metrics、结构化日志、按实例隔离，多实例并存不串扰。

• 基础库设计：可作为库嵌入任意 Go 项目；也是 RuleGo 生态的流处理底座。

5 种窗口，覆盖所有典型形态

窗口	触发方式	典型场景
滚动 Tumbling	固定时长，不重叠	每小时统计一次该小时温湿度
滑动 Sliding	固定时长，固定步长滑动	过去 1 分钟每 10 秒统计一次车流量
计数 Counting	攒满 N 条	每满 100 条设备状态算一次聚合
会话 Session	数据间隔超时	用户连续操作算一个会话，停 5 分钟关闭
全局 Global	TRIGGER WHEN 谓词	阈值告警，与时间无关

两种处理模式，按场景挑

非聚合模式（实时转换/过滤）——每条数据进、立即出，超低延迟。适合数据清洗、实时告警、富化打标、格式转换、内容路由：

ssql.Execute(`
    SELECT deviceId,
           temperature * 1.8 + 32 AS temp_fahrenheit,
           CASE WHEN temperature > 30 THEN 'hot'
                WHEN temperature < 15 THEN 'cold'
                ELSE 'normal' END AS temp_category
    FROM stream
    WHERE temperature > 0`)

// EmitSync：非聚合查询可同步拿结果，立刻返回
result, _ := ssql.EmitSync(map[string]any{"deviceId": "s1", "temperature": 32.5})

聚合模式（窗口统计）——攒一段时间再算，适合监控大盘、性能分析、异常检测、报表生成（代码示例见上面 JOIN 和事件时间两节）。

它适合谁、不适合谁

适合：物联网边缘计算（设备网关、边缘服务器）、实时分析与告警、单机/容器/嵌入式部署、流处理逻辑原型验证、给 RuleGo 规则链加 SQL 流处理能力。

不适合：需要水平扩展的大规模集群、需要持久化状态管理的复杂状态、超出单机能力的超高并发写入、需要 ACID 事务的场景。

与 RuleGo 的协同

StreamSQL 是 RuleGo 生态的组件基础库。RuleGo 提供 MQTT/HTTP/TCP/消息队列等丰富输入源，数据库/邮件/短信/API 等输出源，以及 60+ 数据处理组件。StreamSQL 作为其中的 SQL 流处理能力，配合 RuleGo 的规则引擎和热更新，能在边缘端搭出"低代码 + SQL"的完整数据管线。

---

三、详细更新列表（v0.10.2 → v1.0.0）

v1.0.0（2026-07，115 个提交的核心）

✨ 新特性

• 流-表 JOIN（#39）：INNER/LEFT JOIN，复合键，多表，自定义数据源（TableSource 接口接 DB/Redis/HTTP/文件），键从 ON 自动推导，富化前移使 WHERE 可筛元表列，LEFT 未匹配支持 IS NULL。

• JOIN 支持聚合与窗口：富化结果接入窗口路径，"富化后按维度聚合"端到端可用。

• GlobalWindow + TRIGGER WHEN：对齐 Flink GlobalWindows，FIRE_AND_PURGE + STATETTL。

• 事件时间完善：数值时间戳（int/int64/float64/数值串）全支持；window_id 稳定输出字段（初发与迟到重发 id 一致，下游可幂等去重）。

• CountingWindow State TTL：WITH(STATETTL=...) 清理高基数死 key，默认禁用。

• schema 包：运行期字段类型校验（DataType/Schema/Registry/Validate）+ WithSchema 选项（opt-in，不配零开销）。

• metrics 包：Counter/Gauge/Histogram/Registry，原子无锁；Streamsql.Metrics() 暴露。

• 结构化日志：Field 类型 + StructuredLogger 接口，Text/JSON 双格式，纯增量。

• 按实例 logger：WithLogger，多实例日志不再全局串扰。

• TriggerWindow 公开 API：手动触发当前窗口立即输出（测试与显式 flush）。

⚠️ 行为变更（升级注意）

默认处理时间模式（不带 WITH）行为基本不变；下列变更主要影响事件时间模式。

1. 事件时间缺时间戳的行 → 丢弃（原静默用系统时间，污染水位线）。

2. 整数时间戳未声明 TIMEUNIT → 丢弃（原按秒解释，毫秒时间戳被误判成远未来年份）。正确用法：WITH(TIMEUNIT='ms')。time.Time 字段不受影响。

3. 处理时间窗口对齐到 epoch（原从首条数据起算）。window_start()/window_end() 变为整点边界，多实例/重启后一致（可重放对账）。对齐 Flink / eKuiper。

4. Session 迟到更新包含触发事件（原漏掉，是 bug）。

🐛 Bug 修复（重点）

• 稳定性族：tumbling/counting 构造函数 context 泄漏；Stop 不再 close 业务 channel，确立"靠 ctx/done 退出"模型，消除 send-on-closed panic；Stop join 所有 sink/处理协程（消除泄漏）；Start/Stop 加锁消除并发生命周期数据竞争；Reset 等后台 goroutine 退出。

• 事件时间族：Session 事件时间自死锁；水位线丢包（加补发机制，防末端窗口永不触发）；Session 回调竞争；迟到行不可落位即丢（修 tw/sw.data 无界 OOM）；构造拒零负 duration（防 NewTicker panic 拖垮进程）；watermark 防远未来时间戳毒化。

• 溢出/背压族：overflow Block 超时即丢、Drop 去死分支、丢弃计数拆 input/output；expand 策略消除孤儿 chan 丢行（safeSendToDataChan 持锁发送）；接通 MaxBufferSize 上限（修无界 OOM / 死配置）。

• 解析/函数族：parseLimit 改 token 流识别真 LIMIT（原子串误匹配）；LIKE 含 _/内部 % 走 like_match；array_distinct/intersect/union/except 支持不可哈希元素；fieldpath MapIndex 加类型校验防 panic；percentile 注册为 AggregatorFunction（防 CreateLegacyAggregator panic）；date_format 区分 mm=分钟 / MM=月份；substring 按 rune 切片；cast/ToInt64E/trunc/pow/exp 越界返回错误而非静默回绕/NaN；SELECT * 解析识别星号；is_null/is_not_null 用 reflect 识 typed-nil；row_number 共享实例加锁；LIKE 匹配器改 O(n·m) 双指针。

• 语义：实现 ORDER BY（窗口/批内排序，先排序后 LIMIT）；expr() 动态表达式取行数据修复。

🚀 性能

• ExprBridge 缓存编译后 *vm.Program；编译路径运行环境精简为纯数据；缓存表达式预处理与确定性结果；缓存键改 reflect.TypeOf 免 fmt.Sprintf。

• WHERE 快速路径：单字段比较、扁平 AND/OR、放行字符串字面量（逐段校验保证误拆时回退）。

• 算术表达式走 compiledExpr 快速路径（ComputedFields 提速 33%）。

🧪 测试与质量

• window 包覆盖率 48.7% → 86.8%；补齐事件时间路径与公开方法单测。

• e2e 集成测试迁移至独立包 test/e2e，启用 t.Parallel（314s → 88s，-72%）。

• 新增大数据量并发压测（端到端吞吐 / 峰值堆 / GC 后残留——泄漏检测）。

• CI：覆盖率 -coverpkg=./...、测试 timeout 600s→1200s、benchmark 回归门禁（观察模式）。

🔧 重构 / 依赖

• Stream 指标收敛到 metrics.Registry（input/output/dropped 改 Counter，删废弃 StatsCollector/StatsManager，破坏性）。

• logger 按实例线程化，移除 zero_data_loss、persist 等误导性 no-op。

• interface{} 统一替换为 any（公开 API 文件保留原写法）。

• 升级表达式引擎依赖（v1.17.7 → v1.17.8）。

---

前序小版本

• v0.10.7：支持数组取值；json_extract 支持 map 和 array 入参。

• v0.10.6：window 输出结果增加溢出策略；新增同步获取结果方法（EmitSync）；修复 Session/Counting 窗口 bufferSize 初始化。

• v0.10.5：修复 Trigger 未清除过期数据；修复特殊符号被判非法 / 出现多余字段。

• v0.10.4：增加事件时间窗口处理机制；修复延迟数据处理、事件时间窗口未触发；unnest 正确展开数组为多行；混合 keys 分组、窗口对齐等多项修复。

• v0.10.3：支持聚合函数的后运算；重构聚合函数运算与 SQL 语法解析；提升代码覆盖率。

---

链接

• 文档：https://rulego.cc/pages/streamsql-overview/

• RuleGo 生态：https://rulego.cc