TDengine 表管理 DDL 完全指南：从普通表、带标签表到子表的建表、改表与删表实战

数据库时序数据库物联网大数据实时分析云原生【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址https://gitcode.com/taosdata/tdengine点击查看免费下载本文是 TDengine 时间序列数据库中**表级 DDL数据定义语言**的权威实战指南覆盖CREATE TABLE普通表 / 带自有标签的基本表 / 子表 / CSV 批量建表、ALTER TABLE增删改列、增删改标签、TTL 与 COMMENT以及DROP TABLE的全部语法、参数与限制并结合 docs/en/05-tdengine-sql/02-ddl/02-table.md 与仓库源码如 sql.y 中的 TTL、SMA 语法解析讲清底层原理。读完本文你将能够独立设计 TDengine 表结构、按业务场景选择普通表 / 带标签表 / 子表三种建表路径并安全地完成表结构与标签的在线变更。1. CREATE TABLE 语法总览TDengine 的CREATE TABLE是一条多用途语句既可以创建普通表也可以以超级表supertable为模板创建子表还可以通过TAGS子句创建超级表或创建带自有标签owned 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 }在 sql.y 中可以看到create_subtable_clause被设计成可递归拼接的multi_create_clause这正是批量创建子表在语法层面对一条语句内包含多个建表子句的支持。1.1 建表通用约束约束项说明命名规则表名/列名遵循 TDengine 命名规范字母、数字、下划线不能以数字开头不区分大小写不能使用保留字可用反引号转义详见 命名规则表名长度最大 192 字节不含库名前缀与分隔符首列要求第一列必须是TIMESTAMP系统自动将其设为主键复合主键可通过COMPOSITE KEY关键字将第二列指定为附加复合主键列该列必须是INT、BIGINT、INT UNSIGNED、BIGINT UNSIGNED等整型或VARCHAR、BINARY等字符串类型行长度限制单行最大长度不超过 64 KB每个BINARY、VARCHAR、NCHAR、GEOMETRY、VARBINARY列额外占用 2 字节存储变长列定义使用BINARY、VARCHAR、VARBINARY、GEOMETRY时需指定最大字节数如VARCHAR(20)表示最多 20 个单字节字符使用NCHAR时指定最大字符数如NCHAR(10)表示最多 10 个NCHAR字符压缩配置ENCODE一级编码与COMPRESS二级压缩的算法与默认值见 列压缩1.2 TAGS 子句的双重语义TAGS子句的语义取决于标签是否携带值所有标签均不带值→ 创建的是超级表supertableCREATE TABLE ... TAGS(...)等价于创建超级表的模板结构后续可为其创建子表所有标签均带显式 const_value→ 创建的是带自有标签的基本表 NULL也是合法的显式值部分带值、部分不带值混用→ 语句被拒绝。基本表的自有标签只支持字面量值不支持FROM引用标签不支持DECIMAL类型JSON标签只能在建表时声明且必须是唯一的一个标签列。2. 创建普通表基本表不携带任何标签的最简建表语句CREATE TABLE [IF NOT EXISTS] tb_name (create_definition [, create_definition] ...);示例CREATE TABLE d1001 (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT);2.1 使用 COMPOSITE KEY 定义复合主键除了时间戳主键列TDengine 允许把第二个列指定为复合主键与时间戳共同构成复合键CREATE TABLE sensor_data ( ts TIMESTAMP, device_id INT COMPOSITE KEY, temperature DOUBLE );复合主键列必须是整型INT、BIGINT、INT UNSIGNED、BIGINT UNSIGNED或字符串类型VARCHAR、BINARY。在 sql.y 中column_definition的语法项明确允许type_name [COMPOSITE KEY] [ENCODE ...] [COMPRESS ...] [LEVEL ...]的级联组合。当表使用复合键时只有当时间戳列与第二主键列都相同时两条记录才被视为重复数据库只保留最新一条否则两条记录都被保留。3. 创建带自有标签的基本表当TAGS子句中每个标签都携带显式值 const_value时创建的是带自有标签的普通表CREATE TABLE [IF NOT EXISTS] tb_name (create_definition [, create_definition] ...) TAGS (tag_name1 tag_type1 const_value1 [, ...]);示例CREATE TABLE ntb (ts TIMESTAMP, v INT) TAGS (loc INT 5, dept VARCHAR(16) rd);3.1 自有标签的行为特性自有标签是表级常量投影查询时每一行都会返回该常量值在WHERE过滤中使用时按常量语义求值DESC输出中标签行被标记为TAGSHOW CREATE TABLE返回单条CREATE TABLE ... TAGS(...)语句其中自有标签以 value内联展示NULL 值输出为 NULL可直接回放用于迁移。4. 创建子表基于超级表模板子表以超级表为模板创建继承超级表的全部列与标签定义。创建子表前目标超级表必须已存在见 超级表文档。4.1 最简创建按定义顺序填标签值CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name TAGS (tag_value1, ...);4.2 指定标签名创建可按需填部分标签CREATE TABLE [IF NOT EXISTS] tb_name USING stb_name (tag_name1, ...) TAGS (tag_value1, ...);使用指定超级表作为模板可以只指定部分标签列的值未指定的标签列会被设为 NULL。4.3 一条语句批量创建子表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 语句长度限制的前提下建议单条语句创建 10003000 张子表以获得理想的建表速度。从 sql.y 可以看到multi_create_clause :: multi_create_clause(B) create_subtable_clause(C)的递归语法正是为这种批量写法而设计。4.4 使用 CSV 文件批量创建子表CREATE TABLE [IF NOT EXISTS] USING [db_name.]stb_name (tbname [, tag_name] ...) FILE csv_file_path;参数与约束FILE语法表示数据来自 CSV 文件以英文逗号分隔每个值用英文单引号包裹CSV 文件不需要表头文件内容只应包含tbname和标签值指定的stb_name必须已经存在字段列表顺序必须与 CSV 中列的顺序一致列表不能有重复项且必须包含tbname可以包含零个或多个超级表中已定义的标签列未出现在列表中的标签将被置为NULL如需在批量建表后写入数据参见 数据写入。5. 表选项COMMENT、SMA 与 TTL建表时可通过table_options配置三类表选项。5.1 COMMENT表注释可用于超级表、子表和基本表最大长度 1024 字节。CREATE TABLE d1001 (ts TIMESTAMP, v INT) COMMENT sensor of area 1;5.2 SMA小型物化聚合SMASmall Materialized Aggregates提供基于数据块的预计算用于加速聚合查询。预计算类型包括MAX、MIN、SUM。默认情况下系统会对大多数列按块block-wise创建 SMABINARY、NCHAR等部分类型默认不创建若在创建表时指定SMA(col_name, ...)则只为列出的列创建块级 SMA可用于超级表和基本表。CREATE TABLE d1001 (ts TIMESTAMP, current FLOAT, voltage INT) SMA(current, voltage);在语法层面table_options(A) :: table_options(B) SMA NK_LP col_name_list(C) NK_RP见 sql.y将 SMA 作为表选项解析并挂到建表语句上在管理节点侧mndSma.c 负责 SMA/TSMA 元数据的创建、删除与检索支撑聚合查询的预计算加速。5.3 TTL表生命周期TTLTime to Live用于指定表的存活时长建表时指定该参数后TDengine 会在表存在时间超过 TTL 后自动删除该表。属性说明单位天days取值范围[0, 2147483647]默认值0表示无限制过期时间表创建时间 TTL 时间精确性近似删除系统不保证在精确时刻删除但保证存在该机制且最终会删除与 KEEP 的关系与数据库KEEP参数无关若KEEP小于 TTL数据可能在表被删除前先被清除CREATE TABLE d1001 (ts TIMESTAMP, v INT) TTL 365;从 sql.y 的token_option(A) :: TTL NK_INTEGER(B)规则可以看到TTL的整数值在解析阶段被乘以 86400秒并写入语句选项即建表/改表时 TTL 以天为单位输入、在底层以秒为粒度生效。6. 修改基本表ALTER TABLEALTER 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 }6.1 基本表支持的操作清单操作语法说明增加列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);变长类型列只能加宽、不能缩窄其后可跟ENCODE、COMPRESS、LEVEL压缩选项见 列压缩修改列名ALTER TABLE tb_name RENAME COLUMN old_col_name new_col_name;重命名列添加标签ALTER TABLE tb_name ADD TAG tag_name tag_type;新增自有标签初始值为NULL后续用SET TAG赋值设置标签值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;修改 TTL参数语义同建表单位天范围[0, 2147483647]默认 0修改表注释ALTER TABLE tb_name COMMENT string_value;最大 1024 字节6.2 基本表修改的限制基本表的主键列时间戳列及复合主键列不可修改也不能通过ADD COLUMN/DROP COLUMN增删基本表不支持标签引用ADD TAG ... FROM ...和SET TAG ... db_name.table_name.tag_name均会被拒绝JSON标签不能通过ADD TAG添加只能在建表时声明。7. 修改子表ALTER TABLEALTER 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 }7.1 核心原则子表除了修改标签值外其列与标签结构的增删改都必须通过超级表完成参见 修改超级表不能单独修改某个子表的 schema子表同样支持TTL与COMMENT语义与基本表一致TTL 单位天、范围[0, 2147483647]、默认 0COMMENT 最大 1024 字节。7.2 修改子表标签值ALTER TABLE tb_name SET TAG tag_name1 new_tag_value1, tag_name2 new_tag_value2 ...;7.3 批量修改多个子表的标签值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 ...;注意与批量建表语法类似批量改标签在一条语句中依次列出tb_name SET TAG ...子句可一次更新多个子表的标签。8. 删除表DROP TABLE可以在一条 SQL 语句中删除一个或多个普通表或子表DROP TABLE [IF EXISTS] [db_name.]tb_name [, [IF EXISTS] [db_name.]tb_name] ...;重要说明删除表并不会立即释放其占用的磁盘空间。表的数据会被标记为已删除查询不再返回这些数据但磁盘空间的真正释放要等到系统自动重组数据或用户手动对数据执行压缩COMPACT企业版功能之后。9. 查看表信息9.1 显示所有表SHOW [NORMAL | CHILD] [db_name.]TABLES [LIKE pattern];NORMAL只显示基本表CHILD只显示子表不写关键字时列出指定库或当前库中所有基本表和子表。9.2 显示建表语句SHOW CREATE TABLE [db_name.]tb_name;常用于数据库迁移对已有表返回其创建语句在其他集群执行该语句可得到结构完全一致的表。对于带自有标签的基本表返回的语句会把标签内联为 value形式NULL 值输出为 NULL可直接回放。9.3 获取表结构信息DESCRIBE [db_name.]tb_name;DESCRIBE输出每列的类型、压缩设置等信息标签行在输出中标记为TAG也可用于查看列级ENCODE/COMPRESS/LEVEL配置见 列压缩。10. 源码佐证表 DDL 在 TDengine 中的解析与落盘路径表 DDL 从前端 SQL 到元数据落盘的主链路如下语法解析TDengine 使用自研解析器sql.y 中定义了create_table、create_subtable_clauseL1186-L1189、table_options含 SMAL1320、token_option含 TTLL373等文法规则。TTL NK_INTEGER在解析阶段乘以 86400 转为秒印证了文档中TTL 以天为单位、底层按秒生效的语义multi_create_clause递归文法支撑一条语句批量建子表。元数据管理建表/改表请求到达管理节点mnode后表结构、标签、TTL、SMA 等元数据被持久化。mndSma.c 中的 SMA/TSMA 创建、删除与检索逻辑支撑了表选项SMA(col, ...)的块级预计算能力超级表的列/标签变更会统一作用于所有子表见 mndStb.c。数据写入与压缩COMPOSITE KEY指定的第二主键列与时间戳共同决定记录去重语义列级ENCODE/COMPRESS/LEVEL由数据写入与压缩模块按列配置执行见 列压缩 中的算法与默认值表。11. 关联阅读数据类型与精度TIMESTAMP、BINARY/VARCHAR、NCHAR、DECIMAL、JSON等类型的精确定义与限制是编写column_definition的基础命名规则与限制表名 192 字节、最多 4096 列、最多 128 个标签、标签总长 16 KB 等系统级限制列压缩ENCODE、COMPRESS、LEVEL的可用算法与各类型默认值超级表CREATE STABLE、超级表级TAGS约束最多 128 个标签、总长不超过 16 KB、以及子表 schema 必须通过超级表修改的规则数据写入建表后向子表/普通表写入数据的方式。赞分享数据库时序数据库物联网大数据实时分析云原生【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址https://gitcode.com/taosdata/tdengine点击查看免费下载相关推荐TDengine 虚拟表Virtual Table完全指南DDL 语法、标签引用与虚拟超级表继承TDengine 虚拟表Virtual Table完全指南DDL 语法、标签引用与虚拟超级表继承 导读 虚拟表Virtual Table简称 VTab数据库时序数据库物联网大数据实时分析云原生TDengine 虚拟表Virtual Table完全指南跨表列映射、标签引用与继承式虚拟超级表实战TDengine 虚拟表Virtual Table完全指南跨表列映射、标签引用与继承式虚拟超级表实战 虚拟表Virtual Table是 TDengi数据库时序数据库物联网大数据实时分析云原生TDengine 数据建模实战用 SQL 创建数据库、超级表、子表与虚拟表TDengine 数据建模实战用 SQL 创建数据库、超级表、子表与虚拟表 本文基于 TDengine 官方快速入门中的 Data Modeling 章节以数据库时序数据库物联网大数据实时分析云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考