TDengine 表管理完全指南：CREATE TABLE / ALTER TABLE / DROP TABLE 语法详解-港品优选

TDengine 表管理完全指南：CREATE TABLE / ALTER TABLE / DROP TABLE 语法详解

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

本文是 TDengine SQL 中表（Table）相关 DDL（数据定义语言）的技术指南，完整覆盖基础表、超级表（supertable）模板派生子表、携带自有标签（owned tags）的基础表等多种建表方式，以及列的增删改、标签维护、TTL 生命周期与 COMMENT 注释等修改操作，并介绍表删除与表信息查看。读完本文，你将掌握 TDengine 建表到运维全流程的 SQL 写法、各类限制参数，以及 SMA、TTL 等表级选项的底层语义，可直接应用于 IIoT 场景下的表结构设计。

建表语法总览

TDengine 的CREATE TABLE语句用于创建基础表、以超级表为模板的子表，也可以通过在TAGS子句中声明标签来创建超级表，或创建携带自有标签的基础表。完整的语法定义如下：

CREATE TABLE [IF NOT EXISTS] [db_name.]tb_name (create_definition [, create_definition] ...) [table_options] CREATE TABLE create_subtable_clause CREATE TABLE [IF NOT EXISTS] [db_name.]tb_name (create_definition [, create_definition] ...) [TAGS (tag_def [, tag_def] ...)] [table_options] create_subtable_clause: { create_subtable_clause [create_subtable_clause] ... | [IF NOT EXISTS] [db_name.]tb_name USING [db_name.]stb_name [(tag_name [, tag_name] ...)] TAGS (tag_value [, tag_value] ...) } create_definition: col_name column_definition column_definition: type_name [COMPOSITE KEY] [ENCODE 'encode_type'] [COMPRESS 'compress_type'] [LEVEL 'level_type'] tag_def: tag_name type_name [= const_value] table_options: table_option ... table_option: { COMMENT 'string_value' | SMA(col_name [, col_name] ...) | TTL value }

建表通用约束

无论创建哪种表，都必须遵守以下规则：

表（列）命名规范参见命名规则，合法字符为英文字母、数字和下划线，可以字母或下划线开头，不能以数字开头，不区分大小写，不能使用保留字；如需更灵活的命名（如包含特殊字符、数字开头、保留字），可使用反引号转义。
表名最大长度为 192 字节（不含库名前缀与分隔符）。
表的第一个字段必须是TIMESTAMP类型，系统自动将其设为主键。这一设计是 TDengine 时序数据模型的核心：时间戳作为主键，用于去重、排序与区间查询（参见时间戳规则）。
除时间戳主键列外，可再指定一列作为复合主键（COMPOSITE KEY）。该列必须是整数类型（如INT、BIGINT、INT UNSIGNED、BIGINT UNSIGNED）或字符串类型（如VARCHAR、BINARY）。对于带复合主键的表，仅当时间戳列与第二个主键列均相同时才判定为重复记录，此时数据库只保留最新一条；否则两条记录都保留。
表的最大行长度不能超过 64 KB（自版本 3.0.5.0 起；更早版本为 48 KB）。每一列BINARY、VARCHAR、NCHAR、GEOMETRY、VARBINARY还会额外占用 2 字节存储空间。
使用BINARY、VARCHAR、VARBINARY、GEOMETRY时需指定最大字节数，例如VARCHAR(20)表示最多 20 个单字节字符；使用NCHAR时指定最大字符数，例如NCHAR(10)表示最多 10 个NCHAR字符（每个NCHAR字符占 4 字节）。写入超过声明长度的字符串会报错。
ENCODE与COMPRESS的详细用法参见列压缩。
TAGS子句的语义取决于标签是否携带值：当所有标签均无值时，创建的是超级表；当每个标签都带有显式的= const_value时，创建的是携带自有标签的基础表（= NULL也是合法的显式值）；混合携带值和不携带值的标签会被拒绝。基础表自有标签只支持字面量，不支持FROM引用；标签不支持DECIMAL类型；JSON标签只能在建表时声明，且必须是唯一一个标签。

表级选项：COMMENT / SMA / TTL

COMMENT：表注释，可用于超级表、子表和基础表，最大长度 1024 字节。
SMA：Small Materialized Aggregates（小型物化聚合），提供基于数据块（block）的预计算以加速聚合查询，预计算类型包括 MAX、MIN、SUM。默认情况下，系统会对大多数列自动创建块级 SMA（BINARY、NCHAR等部分类型不默认创建）；如果在建表时指定SMA(col_name, ...)，则只为列出的列创建块级 SMA。SMA 适用于超级表和基础表。从源码结构看，SMA 的实现分散在 executor 等查询执行模块中，块级预计算结果在扫描阶段被直接复用，从而减少对原始数据的实时聚合计算。
TTL：Time to Live，表生命周期参数。建表时指定 TTL 后，表的存活时间超过 TTL 时系统会自动删除该表。TTL 是近似值，系统不保证在精确时刻删除，但保证存在该机制并最终会删除。TTL 单位为天，取值范围[0, 2147483647]，默认 0 表示不限；过期时间为建表时间加 TTL。TTL 与数据库的KEEP参数无关：若KEEP小于 TTL，数据可能在表被删除之前就被清理。

创建基础表

CREATE TABLE [IF NOT EXISTS] tb_name (create_definition [, create_definition] ...);

IF NOT EXISTS可避免重复建表时报错。基础表是最简单的表形态，适合单设备、无标签建模的场景。创建时可配合列级压缩选项：

CREATE TABLE tb1 (ts TIMESTAMP, v INT ENCODE 'simple8b' COMPRESS 'lz4' LEVEL 'medium');

创建携带自有标签的基础表

CREATE TABLE [IF NOT EXISTS] tb_name (create_definition [, create_definition] ...) TAGS (tag_name1 tag_type1 = const_value1 [, ...]);

当TAGS子句中的每个标签都带有显式的= const_value时，创建的是携带自有标签的基础表。例如：

CREATE TABLE ntb (ts TIMESTAMP, v INT) TAGS (loc INT = 5, dept VARCHAR(16) = 'rd');

基础表的自有标签是表级常量：投影该标签时每一行都返回该常量值，在WHERE过滤中使用时按常量语义求值；DESC输出中标签行标记为TAG。SHOW CREATE TABLE会返回单条CREATE TABLE ... TAGS(...)语句，其中自有标签以= value内联（NULL 值输出为= NULL），可直接重放执行，便于迁移。

需要说明的是，JSON标签只能在建表时声明且必须为唯一标签，因此它只能出现在这种"携带标签的基础表"或超级表中；而DECIMAL类型不支持作为标签（参见数据类型中的类型位置限制）。

创建子表

子表是以超级表为模板创建的表，自动继承超级表的列结构，标签值则在本表指定。子表相关操作详见超级表文档。

基本子表创建

CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...);

指定标签列创建子表

CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...);

使用指定超级表作为模板时，也可以只指定部分 TAGS 列的值，未指定的 TAGS 列将设置为 NULL。

批量创建子表

CREATE TABLE [IF NOT EXISTS] tb_name1 USING stb_name TAGS (tag_value1, ...) [IF NOT EXISTS] tb_name2 USING stb_name TAGS (tag_value2, ...) ...;

批量建表要求所有表必须以超级表为模板。在不超过 SQL 语句长度限制的前提下，建议单条语句创建 1000～3000 张表以获得理想的建表速度（默认 SQL 语句最大长度约 4 MB，可通过maxSQLLength参数调整，参见通用限制）。

使用 CSV 批量创建子表

CREATE TABLE [IF NOT EXISTS] USING [db_name.]stb_name (tbname [, tag_name] ...) FILE 'csv_file_path';

参数说明：

FILE语法表示数据来自 CSV 文件（以英文逗号分隔，每个值用英文单引号包裹），CSV 文件不需要表头，内容只应包含tbname和标签值。如需同时写入数据，参见数据写入——INSERT同样支持FILE与USING ... TAGS自动建表组合，可以在写入时按需建表。
为指定的 stb_name 创建子表，该超级表必须已存在。
字段列表的顺序必须与 CSV 文件中的列顺序一致；列表不能有重复项，且必须包含tbname；可以包含零个或多个超级表中已定义的标签列，未在列表中出现的标签值将设置为NULL。

修改基础表

ALTER TABLE [db_name.]tb_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 | RENAME COLUMN old_col_name new_col_name | ADD TAG tag_name tag_type | SET TAG tag_name = new_tag_value | DROP TAG tag_name } alter_table_options: alter_table_option ... alter_table_option: { TTL value | COMMENT 'string_value' }

使用说明

基础表支持以下修改操作：

ADD COLUMN：增加列。
DROP COLUMN：删除列。
MODIFY COLUMN：修改列定义。若数据列为变长类型，可增大宽度，但不能减小。
MODIFY COLUMN之后还可指定ENCODE、COMPRESS、LEVEL等列压缩选项，详见列压缩。
RENAME COLUMN：修改列名。
基础表的主键列不能修改，也不能通过ADD COLUMN/DROP COLUMN增删。
ADD TAG：添加自有标签，初始值为NULL，之后用SET TAG赋值。
SET TAG：设置自有标签的值。
DROP TAG：删除标签。
基础表不支持标签引用：ADD TAG ... FROM ...与SET TAG ... = db_name.table_name.tag_name均被拒绝；JSON标签不能通过ADD TAG添加。

参数说明：COMMENT表注释最大长度 1024 字节；TTL单位为天，范围[0, 2147483647]，默认 0 表示不限，过期时间为建表时间加 TTL，且与数据库KEEP无关。

具体操作示例

增加列：

ALTER TABLE tb_name ADD COLUMN field_name data_type;

删除列：

ALTER TABLE tb_name DROP COLUMN field_name;

修改列宽（仅可增大变长列宽度）：

ALTER TABLE tb_name MODIFY COLUMN field_name data_type(length);

修改列名：

ALTER TABLE tb_name RENAME COLUMN old_col_name new_col_name;

添加自有标签：

ALTER TABLE tb_name ADD TAG tag_name tag_type;

设置标签值：

ALTER TABLE tb_name SET TAG tag_name = new_tag_value;

删除标签：

ALTER TABLE tb_name DROP TAG tag_name;

修改表生命周期：

ALTER TABLE tb_name TTL value;

修改表注释：

ALTER TABLE tb_name COMMENT 'string_value';

修改子表

ALTER TABLE [db_name.]tb_name alter_table_clause; alter_table_clause: { alter_table_options | SET tag tag_name = new_tag_value, tag_name2=new_tag2_value ... } alter_table_options: alter_table_option ... alter_table_option: { TTL value | COMMENT 'string_value' }

使用说明

子表在结构上完全继承超级表，因此除修改标签值外，对子表列和标签的任何修改都必须通过超级表进行（超级表结构变更会自动应用到其全部子表，参见修改超级表）。参数说明同基础表：COMMENT最大 1024 字节；TTL单位为天，范围[0, 2147483647]，默认 0 不限，与数据库KEEP无关。

修改子表标签值

ALTER TABLE tb_name SET TAG tag_name1=new_tag_value1, tag_name2=new_tag_value2 ...;

批量修改子表标签值

ALTER TABLE tb_name1 SET TAG tag_name1=new_tag_value1, tag_name2=new_tag_value2 tb_name2 SET TAG tag_name3=new_tag_value3 ...;

修改表生命周期与注释

ALTER TABLE tb_name TTL value; ALTER TABLE tb_name COMMENT 'string_value';

删除表

可以在单条 SQL 语句中删除一张或多张基础表或子表：

DROP TABLE [IF EXISTS] [db_name.]tb_name [, [IF EXISTS] [db_name.]tb_name] ...;

注意：删除表不会立即释放表占用的磁盘空间，而是将表数据标记为已删除。这些数据不会出现在查询结果中，但磁盘空间的释放要等到系统自动重组数据，或用户使用仅企业版支持的COMPACT功能手动压缩数据后才会发生。这一延迟释放机制同样适用于超级表删除（见删除超级表）。

查看表信息

显示所有表

以下语句可以列出指定数据库或当前数据库中的所有基础表和子表。NORMAL只显示基础表，CHILD只显示子表：

SHOW [NORMAL | CHILD] [db_name.]TABLES [LIKE 'pattern'];

显示建表语句

SHOW CREATE TABLE [db_name.]tb_name;

常用于数据库迁移：对已有表返回其建表语句，在另一个集群中执行该语句即可得到结构完全一致的表。

获取表结构信息

DESCRIBE [db_name.]tb_name;

DESCRIBE除展示列的类型与宽度外，也会展示列的压缩设置（ENCODE/COMPRESS/LEVEL）以及标签行的TAG标记。

小结

TDengine 的表体系以"时间戳主键 + 标签"为核心：基础表适合独立建模，超级表通过模板化结构 + 标签实现海量同类设备的批量管理与高效聚合，携带自有标签的基础表则在两者之间提供了轻量级的标签能力。配合COMPOSITE KEY复合主键、SMA 块级预计算、TTL 生命周期和列级压缩选项，可以在建表阶段就把查询性能、存储效率和数据生命周期策略确定下来。列、标签的在线修改（ALTER TABLE）与延迟释放的删除语义（DROP TABLE）则保证了运行期的灵活性，让表结构可以随着业务演进平滑调整。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析