TDengine 3.x 里有个被严重低估的特性叫 TSMA全称 Time-Series Moving Aggregate中文官方叫法是“窗口预聚集”。我最初看到这个名字时完全没当回事觉得不就是普通的预聚合表吗直到有一次线上一个 5000 万行级的大时间范围聚合查询从 7 秒压到 0.2 秒我才认真去翻了它整个机制。这篇文章就围绕 TSMA 的完整使用手册展开从原理、建法、查询命中条件到各种坑一次性讲完。如果你是正在用 TDengine 做时序聚合分析、或者被“按时间窗口统计平均、峰值”这类查询慢到发愁的开发者和 DBA这篇内容应该能帮你省下不少排查时间。1. 为什么需要TSMA从一次慢查询说起1.1 全量扫描的痛点在 TSMA 出现之前TDengine 里做“按 10 分钟窗口统计电压均值、电流峰值”这类查询靠的是每次查询时实时全量扫描。底层逻辑很简单引擎需要把时间范围内所有原始数据点都读出来按窗口分组再做聚合计算。数据量小的时候没感觉一旦设备数上千、每 5 秒一条数据一个月轻松攒出几千万行这种查询的耗时就会直线上升。我手头有一个设备监控库的真实例子100 台设备每 5 秒上报一条电流电压数据一个月下来大概积了 5184 万行。之前跑“最近 30 天、每 10 分钟统计一次平均电流和最大电压”这种报表查询从发起 SQL 到拿到结果最快也要 5 秒多。如果是并发访问或者报表页面每次刷新都触发一次全量聚合数据库的压力肉眼可见地往上走。这个问题的本质在于计算都发生在查询阶段而查询覆盖的时间范围里绝大部分是已经写入很久的“历史冷数据”。这些数据被反复扫描、反复分组、反复计算每次查询都在做重复劳动。业务上需要的是“最近 30 天的每 10 分钟一个聚合值”这样一个结果而不是“最近 30 天的五千多万行原始记录”但传统引擎的查询路径决定了它必须先读原始数据再现场计算。1.2 TSMA的核心思路让计算发生在写入时TSMA 的思路就是把这个“提前算好”变成系统的原生能力。你在创建 TSMA 的时候定义一个或多个时间窗口和对应的聚合函数引擎会在数据写入时同步更新这些窗口的聚合结果并且以列存的形式持久化保存。等真正的业务查询来了如果发现查询模式和某个 TSMA 匹配优化器就直接读取预聚合结果不再碰原始数据。这个概念可以类比成你家里每个月的水电费账单。如果不做账单你查一年的水费就得把 365 天的每一次用水记录全翻出来加一遍有了账单每个月月底水务公司已经帮你算好了总金额你随时去查只需要看 12 个数字。TSMA 干的就是这件事只不过它把“月账单”细化到了分钟级、小时级窗口并且系统自动维护。这个思路和 OLAP 里的物化视图有点像但 TSMA 的定位更聚焦它专门针对时序数据的时间窗口聚合场景不需要关心复杂的 Join、多维建模因此实现上可以做得非常轻、非常快。而且它是增量更新的——新数据写入时对应窗口的预聚合值跟着更新不需要把整个窗口重算一遍。1.3 TSMA到底适合谁、不适合谁以我这段时间的使用经验来看TSMA 最适合以下几类场景固定窗口粒度的聚合报表比如每 10 分钟、每小时、每天的均值、峰值、累加值。设备状态监控、传感器数据趋势分析这类数据的查询模式高度固定。大时间范围但窗口粒度相对一致的分析比如“过去 90 天的日维度电量统计”。面板类查询同一个图表每次刷新都执行几乎相同的 SQL非常适合走预聚合。反过来有些场景建 TSMA 就是给自己找麻烦即席探索式分析今天按 3 分钟窗口、明天按 17 分钟窗口每次查询模式都不一样TSMA 根本没法覆盖。窗口大于 1 小时的需求TSMA 目前单窗口上限是 3600000 毫秒也就是 1 小时再大的窗口就吃不到了。数据量本身只有几万行的小表全量扫一下也就几十毫秒建 TSMA 反而浪费存储和管理成本。TSMA 不是银弹它更像给“约定俗成”的查询模式做了一层加速层。你能把业务查询固化下来它就帮你把性能拉满如果查询天马行空它也只能干瞪眼。2. 从零开始创建第一个TSMA2.1 确认版本与前置条件TSMA 在 TDengine 3.x 版本引入使用前先确认服务端版本大于等于 3.0最简单的方式是执行SELECT server_version();查看。我遇到过有人拿 2.x 的老库执行 CREATE TSMA 语法直接报语法错误折腾半天才发现是版本问题。另外有一个容易忽略的点TSMA 只能建在普通表或者超级表上子表上不允许创建。而对于超级表来说在建 TSMA 时只需要在超级表上创建一次就能自动覆盖下面所有子表这是最推荐的使用方式。如果你有几十上百张子表不需要逐个去建一个超级表级别的 TSMA 全部搞定。创建 TSMA 还需要有相应的写权限服务端和客户端账号最好都有创建权限。生产环境建议在业务低峰期操作因为创建 TSMA 之后后台会对历史数据逐步构建预聚合窗口在构建完成前会占用一定的 IO 资源。2.2 CREATE TSMA语法逐项拆解直接看语法定义CREATE TSMA [IF NOT EXISTS] tsma_name ON table_name FUNCTION func_name(...) [, func_name(...) ...] INTERVAL(interval_val [, interval_offset]) [SLIDING(slid_val)];逐项拆开来说清楚。tsma_name是自定义的名字建议直接带上窗口粒度和用途比如tsma_10m_avg_current_max_voltage后期维护的时候光看名字就能知道这个预聚合是干嘛的。table_name就是你要建的普通表或超级表。FUNCTION指定一个或多个聚合函数常见支持的有 avg、sum、count、min、max、spread、stddev、first、last不同版本支持的函数可能有些差异以官方文档为准。INTERVAL是核心必填参数表示时间窗口大小取值范围是 1 到 3600000 毫秒也就是最小 1 毫秒、最大 1 小时。interval_offset是可选参数控制窗口对齐的偏移量。比如INTERVAL(10m, 5m)代表窗口大小为 10 分钟但窗口起点从整点后的第 5 分钟开始也就是窗口切成 05~15、15~25、25~35 这种样式。默认不写 offset 时窗口从 1970-01-01 00:00:00 开始自然对齐比如 10 分钟的窗口就是每个小时的 00、10、20、30、40、50 分开始。SLIDING指定窗口滑动步长默认等于INTERVAL这意味着窗口之间没有重叠是滚动窗口。如果希望相邻窗口有重叠比如每 5 分钟产生一个统计、但每个统计覆盖最近 10 分钟的数据就把SLIDING设为 5 分钟这时候INTERVAL(10m)SLIDING(5m)就形成了一个移动平均的效果这也是 TSMA 里 Moving 这个词的来源。这里有一个非常容易踩的坑INTERVAL必须大于等于SLIDING如果SLIDING大于INTERVAL窗口之间会出现空档逻辑上就不成立了引擎会直接报错。所以在做移动平均的时候我习惯先定好业务上需要覆盖的窗口大小再定滑动步长不要反过来。2.3 一个完整的建表与建窗口示例直接上个完整操作序列从建表到建 TSMA 再到查询照着敲就能跑-- 建超级表 CREATE STABLE meters ( ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT ) TAGS ( location BINARY(64), group_id INT ); -- 建TSMA按10分钟窗口预聚合 avg(current) 和 max(voltage) CREATE TSMA tsma_10m ON meters FUNCTION avg(current), max(voltage) INTERVAL(10m); -- 查看TSMA是否创建成功 SHOW TSMA ON meters;建完 TSMA 之后引擎会在后台对历史数据逐步构建预聚合结果。这里有个细节一定要知道如果你刚建完 TSMA 就立刻去执行查询很可能还没走预聚合路径因为历史窗口的预聚合值还没构建完。稍微等一会儿等后台构建完成再测试效果。验证查询是否命中 TSMA可以执行下面这条 SQLSELECT _wstart, avg(current), max(voltage) FROM meters WHERE ts 2024-11-01 00:00:00 AND ts 2024-12-01 00:00:00 GROUP BY _wstart, interval(10m);这条查询的时间范围是 30 天窗口是 10 分钟聚合函数是 avg(current) 和 max(voltage)和前面建的 TSMA 定义完全对齐。只要优化器判定命中查询就不会再去逐行扫描 5000 多万条原始记录而是读取已经算好的窗口聚合值性能差距会有数量级上的差别。3. 查询优化TSMA凭什么能加速3.1 查询优化器如何选择TSMA不是说建了 TSMA所有窗口聚合查询就自动变快了。查询优化器有一个判定的过程我总结下来至少要满足这么几个条件查询语句里必须带时间范围条件比如WHERE ts ... AND ts ...。查询的窗口语法要正常窗口大小尽量和某个 TSMA 的 INTERVAL 完全一致。查询用到的聚合函数必须都在该 TSMA 的 FUNCTION 列表里。查询时间范围至少要覆盖 2 个 TSMA 窗口否则优化器认为直接扫描原始数据更划算。为什么必须带时间范围条件因为 TSMA 是按时间窗口预建立的只有确定了查询的时间边界优化器才能定位到对应的一组预聚合窗口。如果没有时间条件等于要把全表所有窗口都取出来这种场景下优化器通常会放弃 TSMA直接走全量扫描。我见过不少同事建完 TSMA 抱怨没效果结果一看 SQL时间条件已经写全了但窗口粒度从 10 分钟改成了 1 分钟自然对不上。窗口粒度对齐这件事也值得单独强调。假如 TSMA 定义的是INTERVAL(10m)但查询写的是interval(5m)理论上可以用插值机制近似得到结果但优化器不一定会选 TSMA 路径因为插值需要额外的计算和推断可能不比直接全量扫描省多少。所以业务上如果有多个常用窗口粒度比如 10 分钟和 1 小时都用那我建议直接建两个 TSMA一个INTERVAL(10m)、一个INTERVAL(1h)各自覆盖对应的查询模式。3.2 插值机制与窗口对齐TSMA 设计里比较精妙的部分是插值支持。如果查询窗口和 TSMA 预定义窗口不完全对齐比如 TSMA 是 10 分钟窗口查询要的是 15 分钟窗口引擎会取相邻两个 10 分钟窗口的预聚合值做线性插值估算出 15 分钟窗口的聚合结果。好处是仍然不需要去读原始数据还是能在预聚合结果上完成计算。不过这里要泼一盆冷水插值对 avg、sum 这类线性聚合函数比较友好因为均值、加和在窗口合并时本来就是线性关系插值误差很小。但 max、min、first、last 这类非线性函数插值就存在天然的精度损失。举个极端例子某 10 分钟窗口内电压峰值是 380V相邻一个窗口峰值只有 320V如果查询一个跨这两个窗口的 15 分钟窗口线性插值得到的结果和实际真实的最大值 380V 可能有明显偏差。所以我对这种场景的建议是如果业务对峰值、极值要求非常精确查询窗口最好和 TSMA 窗口完全一致不要依赖插值。如果确实需要多种窗口粒度宁可多建几个不同粒度的 TSMA也别指望一个 TSMA 靠插值通吃所有查询。3.3 用EXPLAIN验证是否真正命中判断一条查询到底有没有走 TSMA最靠谱的办法是用 EXPLAIN 看执行计划EXPLAIN SELECT _wstart, avg(current), max(voltage) FROM meters WHERE ts 2024-11-01 00:00:00 AND ts 2024-12-01 00:00:00 GROUP BY _wstart, interval(10m);执行之后如果计划里出现了 TSMA 相关的节点或算子说明查询已经命中预聚合路径优化器正在使用 TSMA 的数据。如果完全看不到 TSMA 的影子就按照前面说的几个条件逐项排查时间条件有没有、窗口粒度是否一致、聚合函数是否在列表里。这个习惯非常值得养成。我见过很多人建完 TSMA看查询时间没降下来就开始怀疑功能有问题其实只要执行一次 EXPLAIN问题出在哪个环节一目了然。EXPLAIN 应该成为验证 TSMA 配置是否生效的第一步而不是最后一步。4. 管理与维护SHOW、DROP、RECONSTRUCT4.1 日常查看与删除TSMA 的管理操作不多日常用得比较多的是查看、删除和重建。-- 查看某个表上的所有TSMA SHOW TSMA ON meters; -- 删除指定的TSMA DROP TSMA tsma_10m ON meters;SHOW TSMA ON meters的输出里能看到 TSMA 名称、所属表、窗口大小、滑动步长、聚合函数列表等信息维护的时候非常有用。如果你建了多个 TSMA想确认某一条查询到底命中了哪个先看 SHOW 的输出再结合 EXPLAIN 去对应。删除 TSMA 的时候有一点要注意如果这个 TSMA 的数据量已经很大删除操作本身也需要写元数据和清理存储文件在线上的大表上执行时建议避开业务高峰期。如果只是临时调整窗口参数不必删掉重建看下一步的 RECONSTRUCT。4.2 表结构变更后的TSMA失效问题这是实际运维中遇到最多的一个坑对表执行了ALTER TABLE增加列、删除列或者修改列类型之后原来建好的 TSMA 可能就不再生效了。原因是 TSMA 底层保存的列式预聚合结果和当前表结构已经不匹配优化器检测到表结构变化后会放弃使用这些预聚合数据。我踩过一次很真实的坑有一张超级表原本有 voltage 列TSMA 建了 max(voltage) 的预聚合。后来因为业务调整我把 voltage 列名改成了 voltage_l1然后查询里也同步改了字段但 TSMA 的元数据还指向旧的列结构结果一段时间内查询性能明显回退全量扫描的耗时又上来了。当时排查了很久最后用下面的命令把 TSMA 重建了一遍才恢复ALTER TSMA tsma_10m ON meters RECONSTRUCT;RECONSTRUCT会基于当前表结构重新构建所有窗口的预聚合结果。这个过程在数据量大时需要一些时间期间会有一定的存储和 IO 开销建议同样放在低峰期执行。重建完成后可以用 SHOW TSMA 验证状态再用 EXPLAIN 确认查询重新命中 TSMA。如果你所在的团队约定定期变更表结构可以考虑把“变更后是否需要对相关 TSMA 做 RECONSTRUCT”写进变更检查清单避免默默踩坑。4.3 配置项与其他限制TSMA 除了语法层面的限制还有一个重量级的配置参数tsmaMaxTables。这个参数控制每个节点上最多能创建的 TSMA 数量默认值因版本有所差异但目的是一样的防止有人无节制地创建大量 TSMA把服务端内存和存储资源耗尽。如果你创建 TSMA 时提示达到上限可以在配置文件中调整tsmaMaxTables修改后需要重启服务端才能生效。另外几个限制需要提前心里有数INTERVAL 和 SLIDING 的单位都是毫秒INTERVAL 上限 36000001小时SLIDING 不能大于 INTERVAL。TSMA 建在子表上不被允许对超级表建即可自动覆盖所有子表。TSMA 的预聚合结果需要额外的存储空间大致在原始数据的 10%~20% 左右视聚合函数个数和窗口重叠度而定。这个量级不算大但也不是零开销建一堆没用的 TSMA 一样会拖累磁盘占用和写入性能。5. 常见问题排查与性能体验5.1 高频问题速查表我在用 TSMA 的实际过程中整理了一份高频问题排查表先压成一张表方便大家快速对照现象可能原因处理方式建了TSMA但查询没变快SQL没写时间范围条件补上 WHERE ts 条件建了TSMA但查询没变快查询的窗口粒度和TSMA不一致调整查询interv或建对应粒度TSMA建了TSMA但查询没变快后台预聚合还没完成等待构建完成再测试执行计划看不到TSMA聚合函数不在TSMA函数列表在TSMA的FUNCTION中补充表结构变更后查询回退ALTER TABLE导致TSMA失效执行ALTER TSMA...RECONSTRUCT创建TSMA失败报参数超范围INTERVAL超过1小时调整INTERVAL ≤ 3600000ms创建TSMA提示数量上限tsmaMaxTables达上限调整配置并重启服务端这张表覆盖了我在社区看到的大部分问题。如果你遇到的情况不在表里最直接的办法就是先执行 EXPLAIN 看执行计划再逐项对照查询条件基本上都能定位到原因。5.2 实测一个千万级表的加速效果说点真实的数据。我在测试环境模拟了 100 台设备、每 5 秒上报一条记录一个月总共约 5184 万行数据。查询需求是最近 30 天、按 10 分钟窗口求平均电流和最大电压。未建 TSMA 时这条查询走全量扫描我这边 SSD 环境下耗时约 5.2 秒。数据量大、窗口数量多的情况下CPU 和磁盘 IO 都被拉满如果同时间有多个并发查询整体响应还会更慢。建好 TSMA 之后同样的查询耗时降到 0.2 秒左右提升幅度大约 25 倍。核心原因很简单全量扫描需要读 5000 多万行原始数据而 TSMA 路径只需要读 100 台设备 × 30 天 × 每天 144 个 10 分钟窗口总共约 43 万行的预聚合结果数据量差了整整两个数量级扫描和计算的开销自然大幅降低。当然这个提升幅度和具体数据分布、查询复杂度、硬件环境都有关。如果你的表只有几十万行TSMA 优势可能不明显因为全量扫描本来也不慢。但数据量一旦到了千万、亿级TSMA 的收益就会非常直观。另一个值得关注的点是查询越频繁、窗口越大、扫描范围越广TSMA 的边际收益越高。这也是为什么面板类报表、监控大屏这种高频重复查询是 TSMA 最典型的受益场景。5.3 实践建议与调优心得最后分享几条这几个月用下来的实操建议都是文档里不常写但真实有用的经验。第一优先在超级表上建 TSMA。一个超级表级别的 TSMA 自动覆盖所有子表不用逐个子表去建管理成本低非常多。如果你在子表上尝试建 TSMA命令直接不通过别在这上面花时间。第二INTERVAL 选业务最常用的窗口粒度。如果业务有多个固定层级比如实时看 10 分钟、日报看 1 小时那就建两个 TSMA各管各的不要在插值上赌精度。第三创建 TSMA 之后不要马上测性能。后台构建历史窗口需要时间一般等几分钟到几十分钟视数据量而定。刚建完立刻测试可能还是全量扫描容易误判“TSMA 没用”。第四把 EXPLAIN 养成习惯。建完 TSMA 先 EXPLAIN 一条业务查询确认执行计划里出现了 TSMA 相关节点再做性能对比。这样能避免把时间浪费在无效优化上。第五留意表结构变更。只要有 ALTER TABLE 操作尤其是涉及列的类型和名称变化马上检查相关 TSMA 状态必要时执行 RECONSTRUCT。这个坑我踩过一次之后已经把它写进了团队的上线检查清单。我个人的体会是TSMA 不是一个能让人第一眼就惊呼“哇”的特性它的价值会在海量数据、高频重复查询的现实场景里逐渐放大。如果你正被“按时间窗口聚合的报表查询越来越慢”这种问题困扰我的建议是先建一个和你业务最匹配的 TSMA用 EXPLAIN 确认命中再慢慢调窗口参数。窗口粒度选对了收益通常会远超预期。