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

-- 创建数据库（全部选项）
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

-- 创建超级表
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（子表/普通表）

-- 创建子表（指定 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

-- 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

-- 流计算
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

-- 用户
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

-- 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;

代码示例

完整建库建表流程

-- 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 演化

-- 加新列
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 后能恢复吗？

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

参考

系统构架篇

• 01-《TDengine 整体架构全景》
• 02-《集群拓扑深度解析》
• 03-《MNode 内部机制深度解析》
• 04-《RPC 通信层深度解析》
• 05-《VNode 生命周期》
• 06-《RAFT 共识协议》
• 07-《端到端的消息流》

数据模型

• 01-《数据库创建与参数详解》
• 02-《超级表/子表/普通表》
• 03-《支持数据类型深度解析》
• 04-《TDengine Tag 设计哲学与 Schema 变更机制》
• 05-《TDengine 虚拟表实现原理》

存储引擎

• 01-《TDengine 存储引擎概览》
• 02-《TDengine MemTable 深度解析》
• 03-《TDengine WAL 预写日志机制》
• 04-《TDengine 数据文件格式》
• 05-《TDengine Commit 与 Flush 机制 》
• 06-《TDengine Compaction 合并策略 》
• 07-《TDengine 数据保留与 TTL》
• 08-《TDengine 压缩编码机制》
• 09-《TDengine Cache 与 Last 查询加速》
• 10-《TDengine 逻辑计划生成》

查询引擎

• 01-《TDengine 查询引擎概览》
• 02-《TDengine SQL 解析与词法分析》
• 03-《TDengine 语义分析与 AST 重写》
• 04-《TDengine 逻辑计划生成》
• 05-《TDengine 物理计划生成》
• 06-《TDengine 扫描算子》
• 07-《TDengine 聚合算子》
• 08-《TDengine 聚合算子》
• 09-《TDengine 连接算子》
• 10-《TDengine 排序、填充与投影》
• 11-《TDengine 分布式查询执行》
• 12-《TDengine EXPLAIN 与查询优化》

数据写入

• 01-《TDengine SQL INSERT》
• 02-《TDengine 无模式写入》
• 03-《TDengine STMT 写入》
• 04-《TDengine 写入内部流程》
• 05-《TDengine 数据更新删除》

数据订阅

• 01-《TDengine 数据订阅》
• 02-《TDengine 订阅 vs Kafka》
• 03-《TDengine TMQ 消费流程》
• 04-《TDengine 内部机制》
• 05-《TDengine TMQ 最佳实践》

预聚合

• 01-《TDengine RSMA》
• 02-《TDengine TSMA --- 时间维度的物化聚合视图》
• 03-《TDengine SMA 内部实现》

索引

• 01-《TDengine Tag 索引》
• 02-《TDengine SMA 索引》

关于 TDengine

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