TDengine 数据表管理完全指南：CREATE / ALTER / DROP / 表信息查询的语法细节与实现原理

TDengine 数据表管理完全指南CREATE / ALTER / DROP / 表信息查询的语法细节与实现原理【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文围绕 TDengine 中数据表普通表、子表、超级表关联的表的全生命周期管理展开完整覆盖CREATE TABLE、ALTER TABLE、DROP TABLE以及SHOW/DESCRIBE等 DDL 语法的语法结构、参数约束与边界限制并结合开源仓库中的解析器sql.y、TTL 管理器metaTtl.c与 SMA 模块source/dnode/vnode/src/sma等源码说明各选项在底层的实现机制帮助读者从语法到原理全面掌握 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系统会自动将其设为主键。除时间戳主键列之外还可以通过COMPOSITE KEY关键字指定第二列为额外的主键列该列与时间戳列共同组成复合主键。当设置了复合主键时两条记录的时间戳列与COMPOSITE KEY列都相同才会被认为是重复记录数据库只保留最新的一条否则视为两条记录全部保留。被指定为主键列的第二列必须为整型或字符串类型如INT、BIGINT、INT UNSIGNED、BIGINT UNSIGNED、VARCHAR、BINARY。在解析器源码中可以直接看到COMPOSITE KEY作为列定义修饰符被识别参见 sql.y 中的建表列定义规则及 command.c 中的校验逻辑。表的每行长度不能超过 64 KB。每个BINARY、VARCHAR、NCHAR、GEOMETRY、VARBINARY类型的列还会额外占用 2 个字节的存储位置。使用BINARY、VARCHAR、VARBINARY、GEOMETRY类型时需要指定最长字节数如VARCHAR(20)表示最多存储 20 个单字节字符使用NCHAR时需要指定字符长度如NCHAR(10)表示最多存储 10 个NCHAR字符。关于ENCODE和COMPRESS的使用参见 按列压缩。TAGS子句的语义取决于标签是否带值全部标签不带值时创建超级表全部标签带 const_value显式值时创建带自有标签的普通表 NULL是合法的显式值部分带值会报错。普通表的自有标签只支持字面量值不支持FROM引用标签类型不支持DECIMALJSON类型标签只允许在建表时声明且必须是唯一的标签。普通表标签的查询与维护方式见下方创建带标签的普通表和修改普通表章节。从解析器源码结构看CREATE TABLE的入口在 sql.y 中CREATE TABLE not_exists_opt full_table_name与CREATE TABLE multi_create_clause分别对应单表含USING建子表与批量建表两种语句形态源码注释明确说明 name TYPE literalmarks CREATE TABLE as normal-table creation with owned tags印证了上文第 8 点中全部标签带显式值即创建带自有标签普通表的语义判定规则。表选项COMMENT、SMA、TTLCOMMENT表注释。可用于超级表、子表和普通表。最大长度为 1024 个字节。SMASmall Materialized Aggregates提供基于数据块的预计算以加速聚合查询。预计算类型包括MAX、MIN和SUM。默认情况下系统会为大多数列创建块级SMA部分类型如BINARY、NCHAR等默认不创建当建表时显式指定SMA(col_name, ...)时仅对指定列创建块级SMA。可用于超级表和普通表。仓库中 source/dnode/vnode/src/sma 目录下的smaCommit.c、smaRollup.c、smaSnapshot.c等文件从源码结构看构成了块级预计算数据的提交、滚动汇总与快照持久化实现元数据侧的 SMA 信息则由 metaSma.c 管理。TTLTime to Live用于指定表的生命周期。指定TTL后当该表的存在时间超过TTL指定的时间后TDengine 会自动删除该表。这个删除时间只是大致时间系统不保证到期后立即删除但会保证最终删除。TTL单位是天取值范围为[0, 2147483647]默认为0表示不限制到期时间为表创建时间加上TTL时间。TTL与数据库KEEP参数没有关联如果KEEP比TTL小在表被删除之前数据也可能已经被删除。TTL 的底层机制可以从 metaTtl.c 得到印证vnode 元数据层维护一个名为ttl.idx的 TDB 索引表其中ttlMgrBuildKey函数将ttlDays、表的changeTimeMs创建时间与表 UID 编码成索引键并计算deleteTimeMs changeTimeMs ttlDays * tsTtlUnit * 1000作为到期删除时间后台 TTL 管理器周期性扫描该索引、找出过期条目并执行删表且通过ttlDropMaxCount控制单轮删除的数量上限——这正是文档所说不保证到期立即删除但保证最终删除的实现基础。创建普通表CREATE TABLE [IF NOT EXISTS] tb_name (create_definition [, create_definition] ...);创建带标签的普通表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(...)语句自有标签内联输出 valueNULL值输出 NULL可直接回放重建。创建子表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 列会设为空值。批量创建子表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 之间将会获得比较理想的建表速度。该批量语句在解析器中对应multi_create_clause规则即单条 SQL 内可串联多个USING ... TAGS (...)子句。注意 SQL 语句最大长度默认为 4194304 个字符可通过参数maxSQLLength配置最大可配置为 64MB批量建表语句长度受此约束。使用 CSV 批量创建子表CREATE TABLE [IF NOT EXISTS] USING [db_name.]stb_name (tbname [, tag_name] ...) FILE csv_file_path;参数说明FILE语法表示数据来自 CSV 文件英文逗号分隔、英文单引号括住每个值CSV 文件无需表头。CSV 文件中应仅包含tbname与标签值。如需插入数据参见 数据写入。为指定的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表示不限制。超过该天数后系统会最终自动删除该表不保证到期立即删除。到期时间按表创建时间起算与数据库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] ...;注意删除表并不会立即释放该表所占用的磁盘空间而是把该表的数据标记为已删除在查询时这些数据将不会再出现但释放磁盘空间会延迟到系统自动建库参数KEEP生效或用户手动进行数据重整时企业版功能COMPACT。查看表的信息显示所有表如下 SQL 语句可以列出当前数据库中的所有普通表和子表信息。NORMAL指定只显示普通表信息CHILD指定只显示子表信息。SHOW [NORMAL | CHILD] [db_name.]TABLES [LIKE pattern];显示表创建语句SHOW CREATE TABLE [db_name.]tb_name;常用于数据库迁移。对一个已经存在的数据表返回其创建语句在另一个集群中执行该语句即可得到一个结构完全相同的数据表。如前文所述对带自有标签的普通表该语句会以内联 valueNULL值输出 NULL的形式还原TAGS子句输出的单条CREATE TABLE ... TAGS(...)语句可以直接回放重建结构相同的表。获取表结构信息DESCRIBE [db_name.]tb_name;DESCRIBE缩写DESC输出表中各列的类型与宽度对带自有标签的普通表标签行会带TAG标记便于区分数据列与表级标签常量。小结TDengine 的表管理 DDL 围绕普通表 / 子表 / 超级表模板三层结构组织建表时通过TAGS子句是否带显式值区分超级表与带自有标签的普通表通过USING从超级表派生子表并通过批量建表与 CSV 批量建表支撑大规模时序场景表选项中的SMA提供块级预计算加速聚合查询、TTL提供表级生命周期管理由 metaTtl.c 中的 TTL 索引与后台管理器实现最终删除语义、COMMENT提供元数据注释日常运维中还可结合SHOW TABLES、SHOW CREATE TABLE与DESCRIBE完成结构查看与迁移。所有约束表名 192 字节、行宽 64 KB、第一列必须为TIMESTAMP等与 命名与边界 附录保持一致在设计与建模阶段应一并纳入考虑。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考