TDengine 超级表(STABLE)完整操作指南:DDL 语法、标签管理与源码实现解析
TDengine 超级表(STABLE)完整操作指南:DDL 语法、标签管理与源码实现解析
超级表(STABLE)是 TDengine 中面向同一类时间序列数据建模的核心抽象:一张超级表统一定义数据列与标签(TAGS)结构,其下挂载的子表共享该结构、各自携带不同的标签取值,从而实现"一表统管、按标签聚合"的物联网与监控数据组织方式。本文以官方 SQL 参考文档为主体,系统讲解超级表的创建、查看、删除与修改等全部 DDL 操作,并结合当前开源仓库的解析器源码与测试用例,深入剖析 CREATE STABLE、ALTER STABLE、SHOW TABLE TAGS 等语句的底层实现,帮助你既会用、又懂原理。
超级表是什么
在 TDengine 中,一张超级表(STABLE)由两部分组成:
- 数据列(column):与普通表一致,用于存储时间序列数据,第一列必须是
TIMESTAMP类型主键; - 标签(TAGS):用于描述子表的静态属性(如设备 ID、地理位置、厂商型号),子表通过标签值区分。
超级表本身不直接存储数据,数据实际存放在基于它创建的子表中。因此对超级表做结构修改(增删列、增删标签)时,TDengine 会自动把改动同步到其下所有子表,这也是超级表 DDL 与普通表最核心的差异之一。超级表配合 SELECT 语句可以完成跨子表的投影、聚合查询,并在 WHERE 子句中对标签进行过滤,是 TDengine 面向海量设备时序建模的基石。
创建超级表
语法
CREATE STABLE [IF NOT EXISTS] [db_name.]stb_name
(create_definition [, create_definition] ...)
TAGS (create_definition [, create_definition] ...)
[BASE ON [db_name.]parent_stb_name [, [db_name.]parent_stb_name] ...]
[table_options]
create_definition:
col_name column_definition
column_definition:
type_name [COMPOSITE KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type']
table_options:
table_option ...
table_option: {
COMMENT 'string_value'
| SMA(col_name [, col_name] ...)
| KEEP value
| VIRTUAL {0 | 1}
}
在解析器源码 sql.y 中可以看到,CREATE STABLE 实际上被解析为与 CREATE TABLE 相同的 createCreateTableStmt 节点,只是通过 stableKeyword = true 标记其超级表身份:
cmd ::= CREATE STABLE not_exists_opt(A) full_table_name(B)
NK_LP column_def_list(C) NK_RP tags_def(D) table_options(E). { ... createCreateTableStmt(pCxt, A, true, B, C, D, E); }
cmd ::= CREATE STABLE not_exists_opt(A) full_table_name(B)
NK_LP column_def_list(C) NK_RP tags_def(D) BASE ON base_on_list(F) table_options(E).
{ ... createCreateInheritedStableStmt(...); }
其中第二种语法对应 BASE ON 继承场景,走 createCreateInheritedStableStmt(见 parAstCreater.c),该函数把父表列表存入 pBaseOnList 并强制 stableKeyword = true。这意味着创建普通超级表和创建继承型超级表在 AST 层共用同一套节点结构,差别仅在于是否携带父表列表。
使用说明
- 超级表名和列名命名规则参见 名称命名规则。
- 非虚拟超级表中列和标签的总数最大为
4096,最少需要 3 个字段:一个TIMESTAMP主键列、一个数据列和一个标签列。虚拟超级表中的数据列最大为32767;标签数量仍最多为128个。 - 第一个字段必须是
TIMESTAMP类型,系统自动将其设为主键。 - 除时间戳主键列之外,还可以通过
COMPOSITE KEY指定第二列为额外主键列。设置复合主键后,只有两条记录的时间戳列和COMPOSITE KEY列都相同,才会被认为是重复记录,数据库只保留最新的一条;否则视为两条记录并全部保留。COMPOSITE KEY列必须是整型(INT、BIGINT、UINT、UBIGINT)或字符串类型(VARCHAR、BINARY)。 TAGS用于定义超级表的标签列,需遵循以下约定:- 标签列名不能与数据列名重复,且不能是未转义的保留关键字。
- 标签最多允许
128个,至少需要 1 个,一个表中标签值的总长度不超过 16 KB。 TAGS中的TIMESTAMP列写入数据时需要提供确定值,暂不支持NOW + 10s这类表达式。
ENCODE、COMPRESS和LEVEL的使用方式参见 按列压缩。COMMENT、SMA等通用表选项说明参见 数据表。KEEP仅对超级表生效,用于设置该超级表的数据保留时长。KEEP的取值格式参见 数据库,但超级表的KEEP与数据库KEEP有以下差异:- 超级表
KEEP不会立即影响查询结果,只有执行数据重整后,过期数据才会被清理并对查询不可见。 - 超级表
KEEP需小于数据库KEEP。 - 数据重整前需要先执行
FLUSH,否则可能不生效。 - 数据重整后再通过
ALTER STABLE修改KEEP并重新执行数据重整时,部分数据是否能被清理取决于对应文件在上次数据重整之后是否有新的数据写入。
- 超级表
VIRTUAL仅对超级表生效。VIRTUAL 1表示创建虚拟超级表,VIRTUAL 0表示创建普通超级表,默认值为0。创建虚拟超级表时,column_definition中只支持type_name,不支持定义额外主键列和压缩选项。虚拟超级表支持通过BASE ON继承其他虚拟超级表的列和标签,详见 虚拟超级表继承。
一个完整示例
-- 创建一个包含设备 ID、温度、湿度三列,以及 location 与 group_id 两个标签的超级表
CREATE STABLE IF NOT EXISTS meters (
ts TIMESTAMP,
device_id INT COMPOSITE KEY,
temperature FLOAT,
humidity FLOAT
) TAGS (
location VARCHAR(20),
group_id INT
);
子表基于该超级表创建后,即可独立写入时间序列数据;对超级表执行 SELECT 查询时,TDengine 会自动聚合其下所有子表的数据。
查看超级表
显示超级表
SHOW [db_name.]STABLES [LIKE 'pattern'];
显示指定数据库或当前数据库下的所有超级表。可以使用 LIKE 对超级表名进行模糊匹配。
显示超级表创建语句
SHOW CREATE STABLE [db_name.]stb_name;
常用于数据库迁移。对一个已经存在的超级表,返回其创建语句;在另一个集群中执行该语句,就能得到一个结构完全相同的超级表。该语句在 sql.y 中对应 createShowCreateTableStmt,与普通表的 SHOW CREATE TABLE 共用同一套建表语句还原逻辑。
获取超级表的结构信息
DESCRIBE [db_name.]stb_name;
返回超级表的列结构、类型、长度以及是否为标签等元信息,可用于快速核对表结构。
获取超级表中所有子表的标签信息
SHOW TABLE TAGS [tag_name [, tag_name] ...] FROM table_name [FROM db_name];
SHOW TABLE TAGS [tag_name [, tag_name] ...] FROM [db_name.]table_name;
示例:
taos> SHOW TABLE TAGS FROM st1;
tbname | id | loc |
======================================================================
st1s1 | 1 | beijing |
st1s2 | 2 | shanghai |
st1s3 | 3 | guangzhou |
Query OK, 3 rows in database (0.004455s)
返回结果集的第一列为子表名,后续列为标签列。通过 SHOW TABLE TAGS 可以在不写 SQL 的情况下快速导出超级表下所有子表及其标签快照,常用于巡检、归档与迁移前的数据盘点。
如果已经知道标签列名称,也可以使用 SELECT DISTINCT 获取指定标签列的值。
taos> SELECT DISTINCT TBNAME, id FROM st1;
tbname | id |
===============================================
st1s1 | 1 |
st1s2 | 2 |
st1s3 | 3 |
Query OK, 3 rows in database (0.002891s)
SELECT 语句中的 DISTINCT 和 TBNAME 都是必不可少的,TDengine 会根据它们对语句进行优化,使之在没有数据或数据非常多的情况下都可以正确并快速地返回标签值。从源码结构看,TDengine 针对 TBNAME + 标签列的组合进行了专门的查询计划优化(相关语法与节点定义可参见 sql.y 与 nodesCodeFuncs.c),因此在数据量极大时该方式比逐行扫描更高效。
获取某个子表的标签信息
taos> SHOW TAGS FROM st1s1;
table_name | db_name | stable_name | tag_name | tag_type | tag_value |
============================================================================================================
st1s1 | test | st1 | id | INT | 1 |
st1s1 | test | st1 | loc | VARCHAR(20) | beijing |
Query OK, 2 rows in database (0.003684s)
SHOW TAGS FROM 返回单个子表的所有标签明细,包含所属数据库、所属超级表、标签名、标签类型与标签值,适合在排查某个具体设备时查看其完整标签画像。
同样,也可以用 SELECT 语句查询指定标签列的值。
taos> SELECT DISTINCT TBNAME, id, loc FROM st1s1;
tbname | id | loc |
==================================================
st1s1 | 1 | beijing |
Query OK, 1 rows in database (0.001884s)
删除超级表
DROP STABLE [IF EXISTS] [db_name.]stb_name;
删除超级表会自动删除通过该超级表创建的子表以及子表中的所有数据。该语句在 sql.y 中通过 createDropSuperTableStmt 生成删除节点,与普通表的 DROP TABLE 走不同的构建函数,以确保级联删除语义在语法层就被显式区分。
注意:删除超级表并不会立即释放该表所占用的磁盘空间,而是把该表的数据标记为已删除,在查询时这些数据将不会再出现,但释放磁盘空间会延迟到系统自动或用户手动进行数据重整时。
修改超级表
ALTER STABLE [db_name.]stb_name alter_table_clause
alter_table_clause: {
alter_table_options
| ADD COLUMN col_name column_type
| DROP COLUMN col_name
| MODIFY COLUMN col_name column_type
| ADD TAG tag_name tag_type
| DROP TAG tag_name
| MODIFY TAG tag_name tag_type
| RENAME TAG old_tag_name new_tag_name
| ADD BASE ON [db_name.]parent_stb_name [, [db_name.]parent_stb_name] ...
| DROP BASE ON [db_name.]parent_stb_name [, [db_name.]parent_stb_name] ...
}
alter_table_options:
alter_table_option ...
alter_table_option: {
COMMENT 'string_value'
| KEEP value
}
在解析器层,ALTER STABLE 与 ALTER TABLE 共用同一套 alter_table_clause 文法,随后通过 setAlterSuperTableType(见 parAstCreater.c)为语句打上"超级表"标记,语法规则对应 sql.y:
cmd ::= ALTER STABLE alter_table_clause(A). { pCxt->pRootNode = setAlterSuperTableType(A); }
这样的设计使得超级表与普通表的 ALTER 文法保持完全一致,区别由后续的元数据管理层依据标记分发处理。
使用说明
修改超级表的结构会对其下的所有子表生效。无法针对某个特定子表修改表结构。标签结构的修改需要对超级表下发,TDengine 会自动作用于此超级表的所有子表。
ADD COLUMN:添加数据列。DROP COLUMN:删除数据列。MODIFY COLUMN:修改数据列宽度。数据列类型必须是可变长类型,如BINARY、VARCHAR或NCHAR;列宽只能改大,不能改小。ADD TAG:添加标签。DROP TAG:删除标签。从超级表删除某个标签后,该超级表下的所有子表也会自动删除该标签。MODIFY TAG:修改标签列宽度。标签类型必须是可变长类型,如BINARY、VARCHAR或NCHAR;列宽只能改大,不能改小。RENAME TAG:修改标签名称。从超级表修改某个标签名后,该超级表下的所有子表也会自动更新该标签名。ADD BASE ON/DROP BASE ON:修改虚拟超级表的继承关系,详见 虚拟超级表继承。- 与普通表一样,超级表的主键列不允许被修改,也不允许通过
ADD COLUMN或DROP COLUMN添加、删除主键列。
增加列
ALTER STABLE stb_name ADD COLUMN col_name column_type;
删除列
ALTER STABLE stb_name DROP COLUMN col_name;
修改列宽
ALTER STABLE stb_name MODIFY COLUMN col_name data_type(length);
如果数据列的类型是可变长类型(如 BINARY、VARCHAR 或 NCHAR),可以使用此语句修改其宽度。列宽只能改大,不能改小。
添加标签
ALTER STABLE stb_name ADD TAG tag_name tag_type;
为超级表增加一个新的标签,并指定新标签的类型。标签总数不能超过 128 个,一个表中标签值的总长度不超过 16 KB。新增标签后,该超级表下所有已有子表的该标签值默认为 NULL。
删除标签
ALTER STABLE stb_name DROP TAG tag_name;
删除超级表的一个标签,从超级表删除某个标签后,该超级表下的所有子表也会自动删除该标签。
修改标签名
ALTER STABLE stb_name RENAME TAG old_tag_name new_tag_name;
修改超级表的标签名,从超级表修改某个标签名后,该超级表下的所有子表也会自动更新该标签名。
修改标签列宽度
ALTER STABLE stb_name MODIFY TAG tag_name data_type(length);
如果标签类型是可变长类型(如 BINARY、VARCHAR 或 NCHAR),可以使用此语句修改其宽度。列宽只能改大,不能改小。
超级表查询
使用 SELECT 语句可以完成在超级表上的投影及聚合查询,在 WHERE 子句中可以对标签和数据列进行筛选。
如果在超级表查询语句中不加 ORDER BY,返回顺序是先返回一个子表的所有数据,然后再返回下一个子表的所有数据,因此返回的数据是无序的。增加 ORDER BY 后,会按 ORDER BY 指定的顺序返回。
注意:除了更新标签值的操作针对子表进行外,其他标签操作(添加标签、删除标签等)均只能作用于超级表,不能对单个子表操作。对超级表添加标签后,基于该超级表创建的所有子表都会自动增加该标签,新增标签的默认值为
NULL。
与虚拟超级表的关系
超级表家族中还存在一类特殊的虚拟超级表(VIRTUAL 1):它本身不直接存储数据,而是通过 BASE ON 从一个或多个父虚拟超级表继承列和标签,用于构建层次化的虚拟表模型。虚拟超级表的创建、查看与修改同样复用本文所述的 CREATE STABLE / ALTER STABLE / SHOW 语法族(BASE ON 子句在 sql.y 中解析为 createCreateInheritedStableStmt),其继承语义、查询展开规则与约束条件详见 虚拟超级表继承。
关键限制速查
| 项目 | 限制 |
|---|---|
| 非虚拟超级表列 + 标签总数 | 最大 4096,最少 3 个字段(TIMESTAMP 主键 + 1 数据列 + 1 标签列) |
| 虚拟超级表数据列 | 最大 32767 |
| 标签数量 | 最多 128 个,至少 1 个 |
| 标签值总长度 | 单表不超过 16 KB |
| 第一个字段 | 必须是 TIMESTAMP,自动设为主键 |
| 列宽修改方向 | 可变长类型(BINARY/VARCHAR/NCHAR)只能改大,不能改小 |
| 主键列 | 不允许修改、不允许通过 ADD/DROP COLUMN 增删 |
超级表 KEEP |
需小于数据库 KEEP,且需 FLUSH 后执行数据重整才生效 |
这些数值约束在 TDengine 使用限制 中有更全面的说明,涉及命名规则、长度上限与关键字使用等细节。
总结
超级表是 TDengine 面向时序数据建模的入口级抽象。掌握本文的 DDL 语法即可完成超级表的全生命周期管理:
- 创建:
CREATE STABLE ... TAGS(...),可选COMPOSITE KEY、按列压缩、KEEP保留期、VIRTUAL虚拟表与BASE ON继承; - 查看:
SHOW STABLES、SHOW CREATE STABLE、DESCRIBE、SHOW TABLE TAGS、SHOW TAGS FROM,以及SELECT DISTINCT TBNAME, ...的标签快速查询; - 删除:
DROP STABLE级联删除所有子表,磁盘空间延迟到数据重整时释放; - 修改:
ALTER STABLE支持增删列/标签、修改列宽与标签名、调整COMMENT与KEEP,所有改动自动下发到全部子表。
在源码层面,超级表相关语句在 sql.y 中与普通表共用 createCreateTableStmt / alter_table_clause 文法,通过 stableKeyword 与 setAlterSuperTableType 标记区分,BASE ON 继承则由 createCreateInheritedStableStmt 单独构建。理解这一设计有助于在实际使用中判断超级表 DDL 的行为边界——尤其是"对超级表的修改会级联到所有子表"这一核心语义。