TDengine DDL 完整参考 — Database/STable/Table/Column/Tag

分类：10.SQL 参考 | 篇章：01 DDL

适用版本：TDengine v3.x（v3.3.x / v3.4.x） | 最后更新：2026-07-14

DDL（Data Definition Language）涵盖数据库、超级表、表、列、Tag 的创建、修改、删除。本文是 TDengine DDL 的速查与详解，含每个语句的关键选项与示例。

核心概念速查表

类别	语句
Database	CREATE/ALTER/DROP/USE DATABASE
STable	CREATE/ALTER/DROP STABLE
Table	CREATE/DROP TABLE
Column	ALTER TABLE ADD/DROP/MODIFY COLUMN
Tag	ALTER TABLE ADD/DROP/MODIFY TAG, SET TAG
Index	CREATE/DROP INDEX

详细解析

1. Database DDL

sql 复制代码

-- 创建数据库（全部选项）
CREATE DATABASE [IF NOT EXISTS] db_name 
  PRECISION 'ms'|'us'|'ns' 
  KEEP days_or_list 
  DURATION days 
  BUFFER mb 
  PAGES n 
  PAGESIZE kb 
  MINROWS n 
  MAXROWS n 
  VGROUPS n 
  REPLICA n 
  WAL_LEVEL 1|2 
  WAL_FSYNC_PERIOD ms 
  WAL_RETENTION_PERIOD seconds 
  WAL_RETENTION_SIZE mb 
  COMP 0|1|2 
  CACHEMODEL 'none'|'last_value'|'last_row'|'both' 
  CACHESIZE mb 
  STT_TRIGGER n 
  RETENTIONS 'level:keep,...'   -- RSMA
  TABLE_PREFIX n 
  TABLE_SUFFIX n;

-- 示例
CREATE DATABASE iot_db 
  PRECISION 'ms' 
  KEEP 365 
  DURATION 10 
  VGROUPS 6 
  REPLICA 3 
  CACHEMODEL 'last_value' 
  CACHESIZE 1024;


-- 修改数据库（仅部分选项可改）
ALTER DATABASE db_name KEEP 730;
ALTER DATABASE db_name WAL_RETENTION_PERIOD 7200;


-- 切换/删除
USE db_name;
DROP DATABASE [IF EXISTS] db_name;

2. STable DDL

sql 复制代码

-- 创建超级表
CREATE STABLE [IF NOT EXISTS] [db_name.]stable_name 
  (column_def [, column_def ...]) 
  TAGS (tag_def [, tag_def ...]) 
  [TABLE_OPTIONS];

column_def ::= column_name data_type [NULL|NOT NULL] [PRIMARY KEY]
tag_def ::= tag_name data_type
TABLE_OPTIONS ::= 
    ROLLUP(func1, func2, ...)
  | COMMENT 'string'

-- 示例
CREATE STABLE meters (
  ts TIMESTAMP, 
  current FLOAT, 
  voltage INT NOT NULL, 
  phase FLOAT NULL
) TAGS (
  location VARCHAR(32), 
  groupid INT
) COMMENT 'electric meters';


-- 修改超级表
ALTER STABLE meters ADD COLUMN power DOUBLE;
ALTER STABLE meters DROP COLUMN power;
ALTER STABLE meters MODIFY COLUMN location VARCHAR(64);
ALTER STABLE meters ADD TAG region VARCHAR(32);
ALTER STABLE meters DROP TAG region;
ALTER STABLE meters MODIFY TAG location VARCHAR(64);
ALTER STABLE meters RENAME TAG old_name TO new_name;


-- 删除（连同所有子表）
DROP STABLE [IF EXISTS] meters;

3. Table DDL（子表/普通表）

sql 复制代码

-- 创建子表（指定 Tag 值）
CREATE TABLE [IF NOT EXISTS] d001 
USING meters TAGS ('Beijing', 1);

-- 批量创建子表
CREATE TABLE 
  d001 USING meters TAGS ('Beijing', 1),
  d002 USING meters TAGS ('Shanghai', 2),
  d003 USING meters TAGS ('Guangzhou', 3);


-- 创建普通表（不属于超级表）
CREATE TABLE [IF NOT EXISTS] normal_t (
  ts TIMESTAMP, 
  val INT
);


-- 修改子表 Tag 值
ALTER TABLE d001 SET TAG location = 'Beijing-North';


-- 删除表
DROP TABLE [IF EXISTS] d001;
DROP TABLE 
  d001, d002, d003;  -- 批量

4. 数据类型

复制代码

完整数据类型列表：

  整数：
    TINYINT          1 字节，-128~127
    SMALLINT         2 字节，-32768~32767
    INT              4 字节
    BIGINT           8 字节
    TINYINT UNSIGNED 1 字节，0~255
    SMALLINT UNSIGNED
    INT UNSIGNED
    BIGINT UNSIGNED
  
  浮点：
    FLOAT            4 字节
    DOUBLE           8 字节
  
  字符串：
    VARCHAR(n)       变长字符串，n 字节
    NCHAR(n)         Unicode 字符串
    BINARY(n)        固定长度二进制
  
  时间：
    TIMESTAMP        8 字节
  
  布尔：
    BOOL             1 字节
  
  特殊：
    JSON             仅 Tag 可用
    GEOMETRY         地理位置
    VARBINARY        变长二进制

5. Index DDL

sql 复制代码

-- Tag 索引
CREATE INDEX idx_name ON stable_name (tag_column);
DROP INDEX idx_name;
SHOW INDEXES FROM stable_name;


-- TSMA
CREATE TSMA tsma_name 
ON stable_name 
FUNCTION(AVG(c1), MAX(c1), MIN(c1)) 
INTERVAL(1h);
DROP TSMA tsma_name;
SHOW TSMAS;

6. STREAM / TOPIC

sql 复制代码

-- 流计算
CREATE STREAM stream_name 
  [TRIGGER ...] [WATERMARK ...] [IGNORE EXPIRED ...] 
INTO target_table 
[TAGS(...)] [SUBTABLE(...)] 
AS subquery;
DROP STREAM stream_name [DROP TABLE];
PAUSE STREAM stream_name;
RESUME STREAM stream_name;


-- TMQ Topic
CREATE TOPIC topic_name AS SELECT ...;
CREATE TOPIC topic_name AS STABLE stable_name;
CREATE TOPIC topic_name AS DATABASE db_name;
DROP TOPIC topic_name;

7. User / Privilege

sql 复制代码

-- 用户
CREATE USER user_name PASS 'password';
ALTER USER user_name PASS 'new_password';
DROP USER user_name;
SHOW USERS;

-- 权限
GRANT READ|WRITE|ALL ON db_name.* TO user_name;
GRANT READ|WRITE|ALL ON db_name.stable_name TO user_name;
REVOKE READ|WRITE|ALL ON db_name.* FROM user_name;
SHOW GRANTS;

8. DNode / VGroup / Cluster

sql 复制代码

-- DNode 管理
CREATE DNODE 'host:port';
DROP DNODE dnode_id;
ALTER DNODE dnode_id CONFIG 'option value';
SHOW DNODES;

-- VGroup 管理
SHOW VGROUPS;
REDISTRIBUTE VGROUP vgroup_id DNODE dnode_id [DNODE dnode_id ...];
BALANCE VGROUP;

-- 集群
SHOW CLUSTER;
SHOW DATABASES;

代码示例

完整建库建表流程

sql 复制代码

-- 1. 创建数据库
CREATE DATABASE power 
PRECISION 'ms' 
KEEP 365 
DURATION 10 
VGROUPS 4 
REPLICA 3 
CACHEMODEL 'last_value';

USE power;

-- 2. 创建超级表
CREATE STABLE meters (
  ts TIMESTAMP,
  current FLOAT,
  voltage INT,
  phase FLOAT
) TAGS (
  location VARCHAR(32),
  groupid INT,
  device_type VARCHAR(64)
) COMMENT 'electric meters';

-- 3. 创建额外索引
CREATE INDEX idx_dtype ON meters (device_type);

-- 4. 创建 TSMA
CREATE TSMA meters_5m ON meters 
FUNCTION(AVG(current), MAX(current)) 
INTERVAL(5m);

-- 5. 创建子表（或写入时自动创建）
CREATE TABLE d001 USING meters TAGS('Beijing', 1, 'TypeA');
CREATE TABLE d002 USING meters TAGS('Shanghai', 2, 'TypeB');

Schema 演化

sql 复制代码

-- 加新列
ALTER STABLE meters ADD COLUMN power DOUBLE;

-- 修改列长度
ALTER STABLE meters MODIFY COLUMN location VARCHAR(128);

-- 加新 Tag
ALTER STABLE meters ADD TAG owner VARCHAR(64);

-- 重命名 Tag
ALTER STABLE meters RENAME TAG groupid TO group_id;

-- 删除列/Tag
ALTER STABLE meters DROP COLUMN phase;
ALTER STABLE meters DROP TAG device_type;

性能考量

DDL 操作开销

操作	开销
CREATE DATABASE	中（创建 VGroup）
CREATE STABLE	低（仅元数据）
CREATE TABLE 子表	极低
ALTER ADD COLUMN	中（全 VGroup 同步）
ALTER MODIFY COLUMN	中
CREATE INDEX	高（扫描元数据）
CREATE TSMA	高（回填历史）
DROP TABLE	低（标记）
DROP DATABASE	低（异步清理）

设计建议

建议	原因
DURATION 适中（10d）	平衡文件数与查询效率
VGROUPS 与节点数匹配	充分利用并行
REPLICA 3 生产推荐	高可用
第一 Tag 最常用	默认索引
CACHEMODEL 'last_value'	加速 LAST 查询

FAQ

Q1: KEEP 多个值是什么意思？

支持分层保留：KEEP 7d,30d,365d 配合 RETENTIONS 使用，实现 RSMA 多层数据各自保留。

Q2: VGROUPS 能修改吗？

不能减少，可以增加（视版本）。建议建库时一次规划。

Q3: ALTER STABLE 影响所有子表吗？

是。所有子表 Schema 跟随超级表。

Q4: DROP DATABASE 是否立即释放磁盘？

异步清理。可通过监控空间确认。

Q5: 超级表 DROP 后能恢复吗？

不能。所有子表数据一并删除。务必谨慎。

参考

系统构架篇

数据模型

存储引擎

查询引擎

数据写入

数据订阅

预聚合

索引

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。