TDengine 3.3.8.1 版本深度解析：ALTER RSMA 增量聚合能力与关键缺陷修复

TDengine 3.3.8.1 版本深度解析：ALTER RSMA 增量聚合能力与关键缺陷修复

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

导读

本文以 TDengine 3.3.8.1（发布日期 2025-10-11）官方 Release Notes 为主体，深入解析该版本唯一的核心增强——ALTER RSMA语句，并结合仓库源码与官方 RSMA 文档，梳理滚动物化聚合（Rollup SMA）的完整生命周期；同时逐条解读 11 项缺陷修复背后的技术场景，帮助运维与开发者在升级到 3.3.8.1 后快速评估影响面、验证修复效果。读完本文，你将掌握 RSMA 的创建、修改、删除、查看与手动计算全流程，并能针对每个修复项设计出可落地的回归验证思路。

版本概览

3.3.8.1 是一个聚焦「稳定性与可用性」的补丁版本：包含1 项增强（Enhancement）与11 项缺陷修复（Fixes），发布时间为 2025-10-11。从修复分布看，该版本覆盖了流式计算（Stream）、物化聚合（RSMA）、连接管理（perf_connections、WebSocket/STMT）、数据同步（taosX decimal）、平台兼容（Windows 本地变量显示）、文件系统（跨设备 move_to）、存储引擎（磁盘刷盘线程死锁）以及消息订阅（带标签过滤条件的 Topic）等多个子系统，是一次覆盖面较广的常规修复版本。

核心增强：ALTER RSMA —— 支持修改物化聚合函数

3.3.8.1 最重要的功能变化是新增ALTER RSMA语句，它补全了 RSMA（Rollup SMA，滚动物化聚合）对象在创建之后缺少的「可变更」能力，使 RSMA 的生命周期管理从「创建—查询—删除」扩展为完整的「创建—变更—查询—删除」。

RSMA 是什么

RSMA 是 TDengine 企业版自 v3.3.8.0 起提供的**降采样存储（downsampled storage）**能力：它按时间窗口对用户数据进行降采样聚合，并将聚合结果落盘保存。其典型适用场景是——原始数据只保留较短时间，而降采样数据需要保留更长时间；由于降采样后数据体积远小于原始数据，可显著降低磁盘占用，且查询可直接扫描降采样结果以获得更快的响应速度（见 RSMA 文档）。

RSMA 具备两类触发机制：

• 自动触发：数据从低存储层级向高存储层级迁移时自动执行降采样，由数据库的KEEP选项（keep0/keep1/keep2）控制，多级存储可参考 多级存储规划；
• 手动触发：当数据发生更新/删除后需要重算降采样结果，或数据已迁移到目标层级但尚未完成降采样时，可手动触发计算。

RSMA 的一个关键语义承诺是：RSMA 不改变查询语义，查询时间范围横跨多个存储层级时，结果中可能同时包含原始数据与降采样数据。

ALTER RSMA 语法与语义

ALTER RSMA [IF EXISTS] [db_name.]rsma_name FUNCTION ([func_name(col_name)[, ...]]);

该语句用于变更列的聚合函数，主要面向新增列的场景。其语义约束在 RSMA 文档中有明确说明，需要注意以下两点：

1. 只能修改此前未显式指定聚合函数的列。在CREATE RSMA时未通过FUNCTION显式指定的列，其聚合函数默认为LAST；
2. 修改默认行为可能改变变更前后的聚合语义，因此官方文档明确提示：操作前务必确认业务需求。

结合CREATE RSMA的语法可以更完整地理解这条约束的来源：

CREATE RSMA [IF NOT EXISTS] rsma_name ON [dbname.]table_name FUNCTION([func_name(col_name)[, ...]]) INTERVAL(interval1[, interval2]);

在创建 RSMA 时，FUNCTION列表可以省略或为空，未显式指定的列一律默认使用LAST聚合；复合主键列只支持FIRST/LAST，未指定时同样默认LAST。ALTER RSMA正是为这种「默认值列」提供事后显式指定聚合函数的能力。

源码佐证：RSMA 变更的消息处理链路

从仓库源码看，RSMA 的管理面逻辑集中在 mnode 的 mndRsma.c。mndInitRsma在 mnode 初始化时注册了一整套消息处理入口：

mndSetMsgHandle(pMnode, TDMT_MND_CREATE_RSMA, mndProcessCreateRsmaReq); mndSetMsgHandle(pMnode, TDMT_MND_DROP_RSMA, mndProcessDropRsmaReq); mndSetMsgHandle(pMnode, TDMT_MND_ALTER_RSMA, mndProcessAlterRsmaReq); mndSetMsgHandle(pMnode, TDMT_MND_GET_RSMA, mndProcessGetRsmaReq);

可见ALTER RSMA在 3.3.8.1 中已成为与CREATE/DROP/GET平级的独立 RPC 消息类型（TDMT_MND_ALTER_RSMA），并配套了TDMT_VND_ALTER_RSMA_RSP应答消息，说明变更操作会经由 mnode 分发到 vnode 侧执行并回传结果——这是一条完整的两阶段消息链路。RSMA 对象本身在 sdb（mnode 的共享数据库）中以SDB_RSMA表持久化，序列化格式中包含name、tbName、dbFName、interval[0/1]、intervalUnit、nFuncs、funcColIds、funcIds等字段，其中聚合函数集合以「列 ID + 函数 ID」的配对数组形式保存，这正是ALTER RSMA修改函数列表时需要更新的核心数据。

RSMA 生命周期管理全景

围绕ALTER RSMA，这里将 RSMA 对象管理的完整命令族一并梳理（均出自 RSMA 文档）：

其中SHOW CREATE RSMA的官方示例输出如下，可作为验证ALTER RSMA生效与否的直观手段：

taos> SHOW CREATE RSMA rsma7\G; *************************** 1.row *************************** RSMA: `rsma7` Create RSMA: CREATE RSMA `rsma7` ON `d0`.`stb1` FUNCTION(min(`c0`),max(`c1`),avg(`c2`),sum(`c3`),first(`c4`),last(`c5`),first(`c6`)) INTERVAL(60000a,300000a) Query OK, 1 row(s) in set (0.005250s)

CREATE RSMA 的 INTERVAL 约束（修改时同样受其影响）

ALTER RSMA只修改函数列表而不修改INTERVAL，因此创建时的窗口约束对理解降采样行为仍然关键：

• INTERVAL必须指定 1～2 个值，取值范围[0, DURATION]（按数据库精度换算），且至少一个非0；interval1 = 0表示第 2 层不做降采样，interval2 = 0表示第 3 层不做降采样；
• 必须带时间单位，允许：a（毫秒）、b（纳秒）、u（微秒）、s（秒）、m（分钟）、h（小时）、d（天）；不支持w/n/y；
• 两个 interval 均为正时要求interval1 < interval2，且interval2必须是interval1的整数倍；两者均不得超过数据库DURATION，且DURATION应能被每个正 interval 整除，以降低跨文件边界计算的复杂度、资源消耗与碎片化；
• 令interval2为interval1的整数倍，可保证MIN/MAX/SUM/FIRST/LAST相对原始数据的正确性；AVG仍可能存在误差。

缺陷修复逐条解析

1. 时间戳列上同时执行 first / last 函数返回错误结果

该修复针对的是同一查询中、同一时间戳列上同时执行FIRST与LAST时结果不正确的问题。FIRST/LAST是 TDengine 中最常用的时序语义函数，在聚合执行器（executor）中通过保留窗口内首末行记录实现；同一列被两个函数同时引用时，若执行器对共享状态（如首末行指针、分组上下文）处理不当，就会产生交叉污染。建议在升级后用如下形态的语句回归验证：

SELECT FIRST(ts), LAST(ts) FROM stb INTERVAL(1m);

2. 周期触发模式下，taosd 重启后首个窗口计算结果不正确

该修复针对Stream（流式计算）在周期触发（periodic trigger）模式下，taosd 重启后首个窗口计算结果错误的问题。流计算的状态（已计算窗口边界、触发游标）在重启后需要从 WAL / 检查点恢复，若首个窗口的边界恢复逻辑存在偏差，会导致窗口内容不完整或重复计算。该问题与窗口边界持久化强相关，可在 CI 场景中用「写入数据 → 重启 taosd → 检查首个窗口聚合结果」的方式做重启一致性回归。

3. perf_connections 中 end_point 信息不正确

perf_connections是 TDengine 的连接性能监控表（TSDB_MGMT_TABLE_CONNS，可见于 profile.cpp 的单元测试引用）。该修复修正了连接表中end_point（远端端点地址）信息展示不准确的问题——通常与连接建立时端点的解析/记录时机有关。升级后可通过SELECT * FROM perf_connections观察各连接的end_point是否与实际客户端来源一致。

4. taosX 同步 decimal 数据时的精度丢失

该修复针对taosX 数据同步工具在传输DECIMAL类型数据时发生精度丢失的问题。DECIMAL属于精确数值类型，跨端序列化/反序列化或中间格式转换（如 JSON、字符串）时若未保留 scale 信息，就会引入精度损失。仓库中 decimal 实现位于 source/libs/decimal，涉及DECIMAL的编码解码路径均可作为排查范围。回归方法：构造高精度 decimal 数据经 taosX 同步后，对比源库与目标库的逐位数值是否一致。

5. Windows 平台上 show local variables like 'timezone' 显示不正确

该修复针对Windows 平台下SHOW LOCAL VARIABLES LIKE 'timezone'显示错误的问题。本地变量（local variables）中的timezone取值依赖操作系统时区探测，Windows 与时区相关的 API（如GetTimeZoneInformation）与 POSIX 时区命名体系存在差异，容易导致解析失败或显示异常。升级后在 Windows 上执行上述语句即可验证。

6. 流计算 count 窗口指定 DELETE_RECALC 选项后未报错

该修复针对的是：流计算使用 count 窗口（count window）时指定DELETE_RECALC选项后，系统未报告错误的问题。DELETE_RECALC是流式任务的触发选项之一，其枚举定义与解析可见于 parAst.h 与 sql.y：STREAM_TRIGGER_OPTION_DELETE_RECALC表示数据删除后触发重算。问题在于——DELETE_RECALC依赖删除事件的时间语义，而count 窗口以「行数」而非「时间」为窗口边界，两者语义上不兼容，因此正确行为应当是在创建 stream 时直接拒绝该组合。本次修复即为在该场景下补充参数合法性校验并报错，防止用户创建出行为不符合预期的流任务。

7. 修复若干 Explorer 拼写错误

属于纯界面/文案层修复，修正了 TDengine Explorer 中的若干拼写错误，不影响功能行为。

8. move_to 跨设备（cross-dev）失败

该修复针对文件移动操作move_to在**跨设备（cross-device）**场景下失败的问题。跨设备移动在底层往往需要「复制 + 删除」而非简单的rename(2)（后者跨文件系统时会返回EXDEV），若实现未处理该回退路径就会失败。从仓库结构看，文件移动相关逻辑位于 source/os/src/osFile.c（os模块封装了跨平台文件操作）。升级后可在启用了多级存储/不同挂载点的环境上验证文件迁移与层级流转是否正常。

9. 使用 STMT 时 WebSocket 重连导致崩溃

该修复针对WebSocket 连接在重连过程中使用 STMT（预编译语句）时触发崩溃的问题。STMT 在连接上下文（连接句柄、参数绑定结构）中持有会话状态，WebSocket 重连会重建底层连接对象，若 STMT 上下文的指针未随重连更新或释放时机不当，即可能悬垂引用崩溃。相关代码路径可参考 source/client/wrapper（C 接口封装）与 STMT 实现。回归方法：通过 WebSocket 建立连接 → 执行 prepare/bind/execute → 强制断线重连 → 再次执行 STMT，反复循环验证稳定性。

10. 高负载读写下磁盘刷盘线程可能死锁

该修复针对大量写入与查询并发时，磁盘刷盘（disk flush）线程可能发生死锁的问题。刷盘线程与查询/写入路径存在锁竞争（如文件锁、缓冲区锁、vnode 锁），在极端并发下若锁获取顺序不一致，可能形成循环等待。此类死锁通常伴随 taosd 日志中的刷盘线程长时间无进展、写入延迟飙升等特征。升级后可通过高并发读写压测观察刷盘线程（如taosd线程列表中的 flush 相关线程）是否持续正常运行。

11. 订阅带标签选择条件的 Topic 时标签过滤未生效

该修复针对数据订阅（TMQ）场景下，订阅一个带 tag 选择条件的 topic 时，tag 过滤条件未生效的问题。订阅端在消费数据时需按 topic 定义中的 tag 条件过滤数据，若过滤谓词在下推或消费端应用阶段丢失，订阅者就会收到本应被过滤掉的数据。回归方法：创建一个带 tag 过滤条件的 topic（如SELECT * FROM stb WHERE tag1 = 'x'），订阅并消费，确认仅收到满足条件的行。

升级与回归建议

结合本版本增强与修复内容，建议按以下顺序制定升级后的回归清单：

1. RSMA 相关：若使用企业版降采样存储，重点验证ALTER RSMA对新增列的聚合函数修改是否生效（用SHOW CREATE RSMA比对），并确认修改前后业务对聚合语义的预期；
2. 流计算相关：覆盖 count 窗口 +DELETE_RECALC的非法组合应报错、周期触发模式下重启 taosd 后首窗口计算正确、FIRST(ts)+LAST(ts)同列联查结果正确；
3. 连接与订阅：WebSocket + STMT 断线重连循环、带 tag 过滤条件的 Topic 订阅过滤、perf_connections的end_point显示；
4. 存储与平台：多级存储/跨设备场景下的move_to、高并发读写下的刷盘线程稳定性、Windows 平台timezone本地变量显示、taosX 同步 decimal 精度。

以上修复大多属于行为正确性修正，升级后可通过针对性的 SQL 与场景测试快速验证；对于未涉及 RSMA 与上述场景的业务，3.3.8.1 可视为低风险的稳定性补丁版本。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine