TDengine TSDB 官方手册阅读指南：时序数据模型、角色化学习路径与内核架构地图

TDengine TSDB 官方手册阅读指南：时序数据模型、角色化学习路径与内核架构地图

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

本文是 TDengine® TSDB（以下简称 TDengine）官方用户手册的阅读指南，帮助架构师、开发者与系统管理员按角色快速定位所需章节，同时系统梳理时序数据基础概念、"一表一采集点 / 超级表 / 虚拟表"三大数据模型、SQL 时序扩展以及内置缓存、流计算、数据订阅等核心能力。读完本文，你将掌握 TDengine 文档的整体脉络，明确不同角色应从哪份文档入手，并能沿着仓库内真实路径深入源码与内部设计。

TDengine TSDB 是什么

TDengine 是一款开源、云原生（cloud-native）的时序数据库（Time-Series Database，TSDB），专为物联网、车联网、工业互联网、金融、IT 运维等场景而设计。它内置了缓存（Cache）、**流计算（Stream Processing）与数据订阅（Data Subscription）**能力，能够在很大程度上降低系统设计的复杂度以及开发、运维成本，是一个面向时序数据的一体化平台。

这份阅读指南所对应的官方用户手册覆盖了基础概念、安装、使用、特性、开发接口、运维与内核设计等全部主题，面向三类核心读者：

• 架构师：关注整体选型、数据建模与集群规划；
• 开发者：关注连接、写入、查询、订阅与流计算等编程能力；
• 系统管理员：关注安装部署、集群运维、监控与调优。

如果对时序数据本身的价值与业务含义尚不熟悉，建议先阅读时序数据基础；而无论扮演何种角色，正确使用 TDengine 之前都应仔细阅读基本概念。

按角色定位章节：四条阅读路径

官方手册按读者角色给出了清晰的阅读路径，下表汇总了四条主线及其对应章节：

开发者：从开发者指南起步

手册建议开发者按以下开发路径逐步深入：

1. 选择连接方式：无论使用何种编程语言，都可以通过 REST API 访问 TDengine；多数语言还提供了专用连接器，详见连接器参考；
2. 设计数据模型：根据场景与数据特征决定建库数量，区分静态标签与采集量，创建正确的超级表，再按需创建子表；
3. 选择写入方式：支持标准 SQL 写入、参数绑定（Parameter Binding）写入，以及免建表的 Schemaless 写入（兼容 InfluxDB / OpenTSDB 等行协议）；
4. 编写查询 SQL：完成统计、过滤与分析；
5. 实时统计分析：轻量级实时统计（含监控大屏）优先使用流处理，而非部署 Spark、Flink 等重型流系统；
6. 消费新写入的数据：需要实时消费新数据时，优先使用数据订阅而非部署 Kafka 等消息队列；
7. 获取最新状态：如车辆管理等需要每个采集点最新状态的场景，优先使用 TDengine 内置 Cache，而非单独部署 Redis；
8. 扩展计算能力：内置函数不满足需求时，使用用户自定义函数（UDF）扩展计算逻辑。

开发者指南还提供示例代码目录（C、Java、Go、Python、Rust、Node.js、C# 等多语言示例），且示例正确性由 CI 覆盖，对应脚本位于 test/cases/83-DocTest。

系统管理员：从运维与工具入手

大数据时代，单机垂直扩展无法满足持续增长的业务需求，系统普遍需要水平扩展能力，集群化已成为大数据与数据库系统的必备能力——TDengine 团队不仅实现了集群，还将这一核心能力开源。运维章节专门介绍集群的规划、部署、维护与监控。

内核与开源：阅读TDengine 内部设计

该章节覆盖分布式架构、存储引擎、查询引擎、虚拟表查询优化、数据订阅（TMQ）、流处理、缓存、压缩与日志，建议结合开源仓库中的源码一同阅读。以架构篇 01-arch.md 为例，其定义了物理节点（pnode）、数据节点（dnode）、虚拟节点（vnode）、管理节点（mnode）、计算节点（qnode）、流计算节点（snode）与虚拟节点组（vgroup）等完整逻辑单元，并说明了基于 Raft 协议的主从复制、同步复制、Learner 角色扩展与写路径细节。

先补基础：时序数据的十个特征与典型场景

时序数据基础归纳了时序数据的十个特征，是理解 TDengine 设计取舍的前提：

1. 数据按时间有序且总带时间戳；
2. 数据是结构化的，且多为数值；
3. 每个采集点是一条数据流，来源唯一；
4. 更新与删除很少发生；
5. 事务不那么关键；
6. 相对互联网应用属于写多读少；
7. 用户更关心一段时间内的趋势而非单点值；
8. 数据有保留周期，可批量删除过期数据；
9. 需要实时分析（秒级告警与决策）；
10. 流量平稳且可预测，可精确估算带宽与存储。

典型应用场景包括：电力与能源、车联网/轨道交通、智能制造、智慧油田、IT 运维、金融量化交易等。这些场景共同的特点是：数据量大、写入持续、需要实时计算与低成本存储，这正是通用大数据栈（Hadoop 生态 + Kafka + Redis + Flink 等）力不从心之处——通用栈存在开发效率低、运行效率低、运维成本高、产品交付慢、小规模私有部署过重等结构性缺陷，因而需要专为时序数据设计的平台。

三大数据模型：一表一采集点、超级表与虚拟表

TDengine 充分利用了时序数据特性，提出了"一表一数据采集点"、"超级表"与"虚拟表"三类数据模型，并设计了创新的存储引擎，显著提升了写入、查询与存储效率。官方手册以智能电表为例说明这些概念：电表采集 current（电流）、voltage（电压）、phase（相位）三个量，并带有 location（位置）与 groupid（组 ID）两个静态属性。

指标（Metric）与标签（Tag）

• 指标（Metric）：从传感器、设备等处获得的物理量，如电流、电压、温度，随时间变化，数据量持续增长；
• 标签（Tag）：与采集点关联的静态属性，如型号、颜色、位置，数据量相对稳定，可增删改。

一表一数据采集点

TDengine 采用传统关系型数据库模型管理数据，同时要求每个数据采集点（DCP）一张表。这一设计带来四重收益（详见 02-basic-concepts.md）：

1. 每个采集点数据源唯一、单表单写者，可实现无锁写入，大幅提升写速；
2. 采集点数据天然按时间有序，写入采用append-only 追加方式；
3. 单点数据在块内连续存储，按时间段读取可显著减少随机读；
4. 数据块内采用列式存储，可按数据类型选择不同压缩算法，压缩率高。

表的第一列必须是时间戳，TDengine 会基于该时间戳建索引并做列式存储。

超级表（Supertable）与子表（Subtable）

当设备数量激增时，跨采集点聚合操作面对海量表会异常繁琐。超级表将结构相同、静态属性不同的采集点聚合成一个逻辑统一表：一个超级表包含多个子表，子表结构相同但标签值不同；子表结构不能直接修改，但修改超级表的列与标签会立即对所有子表生效；超级表本身只定义模板，不存储数据与标签。查询超级表时，TDengine 先通过标签过滤出符合条件的表，再对各子表查询时序数据并合并结果，从而高效实现跨采集点的聚合分析。下图展示了指标、标签、超级表与子表的关系：

虚拟表（Virtual Table）

现实中的设备往往包含多个采集频率不同的传感器（如风机的电气、环境、机械参数），单表描述困难，多表又会引发多层 Join 的性能问题。为此 TDengine 引入虚拟表（VTable）：它不存储物理数据，而是在查询时动态合并多个源表（子表或普通表）的列来完成分析计算。虚拟表分为虚拟超级表、虚拟子表与虚拟普通表，支持按时间戳对齐合并、缺失值以 NULL 填充、自动反映源表变化，且不可写入、不可删除、只可查询。这一机制让"先写入、后建模"成为现实：采集阶段可按贴近设备协议的形态（如单列模型）写入，事后按业务视图创建虚拟表，降低采集复杂度与前期建模负担。

数据库（Database）与时间戳（Timestamp）

• 数据库：管理一组表的集合，一个实例可含多个库，每个库可配置不同的存储策略（采集频率、保留周期、副本数、数据块大小等），建议将数据特征不同的超级表放入不同数据库；一个超级表只能属于一个库，其所有子表也存放于该库。
• 时间戳：TDengine 存储 UTC 时间戳。写入时，RFC-3339 格式（带时区）会被正确解析为 UTC；非 RFC-3339 格式则按应用时区转换。查询时客户端自动将 UTC 时间戳转换为应用时区的本地时间。

以 SQL 为查询语言：面向时序的扩展

TDengine 使用 SQL 作为查询语言以降低学习与迁移成本，并为时序场景扩展了**插值（interpolation）、降采样（downsampling）、时间加权平均（time-weighted averages）**等能力，详见 TDengine SQL 章节。该章节详细描述了 SQL 语法规则、数据类型、数据定义、数据写入、数据查询、函数与常见限制。

值得注意的实现细节：TDengine SQL 语句默认最大长度为 4 MB，可通过客户端参数maxSQLLength配置（范围 1 MB 至 64 MB）；且不支持关键字缩写，例如DELETE不能简写为DEL。手册还以智能电表为例给出了典型的表结构（DESCRIBE meters）：ts（TIMESTAMP，主列）、current（FLOAT）、voltage（INT）、phase（FLOAT），以及两个标签列location（BINARY TAG）与groupid（INT TAG）。

内置能力：缓存、流计算与数据订阅

缓存（Cache）

TDengine 采用时间驱动的缓存管理策略（写驱动）：将最新写入的数据优先保存在集群缓存中，每个 vnode 拥有独立的、按固定大小内存块划分的隔离内存空间，并使用 SkipList 加速检索；当超过三分之一的内存块被写满时触发落盘（相关参数如数据库参数buffer）。基于此，合理配置数据库参数后可直接将 TDengine 用作数据缓存，无需再部署 Redis 等额外缓存系统。此外还提供last_row/last的 LRU 缓存（由数据库参数cachemodel控制，取值none、last_row、last_value、both），可高效返回每个设备的最新状态，详见 07-cache.md 与架构篇中的"缓存与持久化"小节。

流计算（Stream Processing）

TDengine 的流计算引擎提供以 SQL 定义实时转换的能力：数据写入流的源表后，按定义自动处理并把结果按触发模式推送到目标表，在高吞吐写入下仍可达到毫秒级结果延迟。相比传统流处理，它实现了触发—计算解耦：触发源与计算源可以分离（可不同表，甚至无需触发表）；触发机制除"数据写入"外还支持基于窗口（窗口开启、关闭或两者）与定时等时间无关触发，并可在触发前对触发数据预过滤；计算范围不设限，任何查询语句都可用于计算，结果可作通知、写入输出表或两者兼具。注意：新的流处理特性自v3.3.7.0起支持。

数据订阅（Data Subscription）

数据订阅提供类似消息队列的订阅消费接口：用户定义topic（可为一个数据库、一张超级表，或一条基于现有表的查询语句），通过 SQL 过滤标签、表名、列或表达式，并可应用标量函数与 UDF（不可聚合）。订阅端可组成消费者组共享消费进度，实现多线程/分布式消费；一个消费者可订阅多个 topic。其核心机制是：TDengine 自动为**预写日志（WAL）建立索引以支持快速随机访问，并提供可配置的文件轮转与保留策略（WAL 保留时间与大小），使 WAL 成为持久化、保持到达顺序的存储引擎；查询型 topic 按当前 offset 从 WAL 读取数据，经统一查询引擎过滤转换后推送给消费者，并提供 ACK 机制实现崩溃、重启场景下的至少一次（at-least-once）**投递。

两点版本相关的运维约束（来自官方文档原文）：

• 自v3.2.0.0起订阅支持 vnode 迁移与分裂，但迁移/分裂时 WAL 不参与同步，因此迁移或分裂 vnode 前必须消费完未完成的 WAL 数据；
• 自v3.3.7.0起可用 MQTT 客户端订阅已有 topic（见 03-mqtt.md）。

集群架构与存储引擎速览

若想深入内核，架构篇是起点，其核心要点包括：

• 逻辑单元：pnode（物理节点，按 FQDN 标识）→ dnode（taosd 运行实例，按 FQDN+端口组合的 endpoint 唯一标识）→ vnode（数据分片与负载均衡的基本工作单元，存储一部分时序数据及其表结构与标签元数据）；mnode 负责集群元数据与节点管理（最多 3 个，基于 Raft 协议，首个节点部署时自动创建）；qnode 负责查询计算（实现存储与计算分离）；snode 负责流计算（实现流计算与批量计算分离）。
• 一致性：vgroup 由不同 dnode 上的 vnode 组成，采用 Raft 协议，只有 leader 可接受写入；同步复制时 leader 需等待超过半数副本确认后才向应用返回成功，并通过流水线复制算法（pipeline replication）平衡一致性与写性能；通过引入不参与投票的Learner角色扩展 Raft，以快照同步 + 日志追赶的方式平滑完成节点扩容与副本调整。
• 分片与分区：以一致性哈希将表分配到 vnode（单 vnode 最多容纳约 100 万张表，单表数据不跨 vnode 分散），再按时间周期（数据库参数duration）将数据文件分区，配合保留期参数keep自动删除过期文件；支持dataDir多挂载盘与最多 3 层分级存储（tier_level0/1/2，primary主挂载点、disable_create_new_file等配置项），并可通过alter dnode动态调整（注意：分级存储仅 TSDB 企业版支持）。
• 写入路径：leader 写入依次为接收校验 → 写 WAL（wal_level=2且wal_fsync_period=0时立即持久化）→ 转发给 follower（含版本号）→ 写入内存并更新 SkipList → 返回确认；follower 仅执行写 WAL 与写内存两步。
• taosc 与重定向：应用通过 taosc 与集群交互，taosc 缓存元数据与 vgroup 拓扑、自动重定向到 leader；新 dnode 通过dnode.json→firstEp/secondEp→ 自身 endpoint 的三步流程获取 mnode 地址并加入集群。

进阶组件：TDengine IDMP

如果需要在工业场景中获得可视化、事件管理、根因分析与 AI 洞察能力，可进一步了解平台的另一组件 TDengine IDMP——一个 AI 原生工业数据管理平台，能够基于采集数据自动感知应用场景、免提示生成仪表盘与报表、进行实时分析并检测异常，形成面向实时决策的工业智能体。

文档地图与社区参与

为便于快速检索，将上文提到的核心文档路径汇总如下：

TDengine TSDB（包括这份文档本身）是一个开源项目，欢迎社区参与贡献：如果在文档中发现错误或描述不清之处，可点击页面底部的Edit this page提交修改；若需查看源码，可访问仓库根目录并重点关注 source（服务端各模块实现，如 dnode、libs、common）与 docs（中英文文档与示例代码）。一起，让这个时序数据库变得更好。

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