建表规范
表类型选择
建表前必须先确定表类型，三种类型不可互转（除单表→分区表）：
表类型 | 适用场景 | 特点 |
普通表（单表） | 数据量小、无分布需求 | 所有数据在一个 RG |
分区表 | 大数据量、需水平扩展 | 数据按规则分布到多 RG |
同步表 | 系统配置、维度表、读多写少 | 全节点强同步副本 |
主键规范
必须显式定义主键，无主键会导致写入热点（Write Hotspot）
避免单调递增主键（如纯自增 INT），同样会造成写入热点，推荐使用复合主键或带随机性前缀
自增列必须独立作为主键或唯一索引，否则可能出现值重复
自增值只保证全局唯一，不保证连续（分片缓存机制，默认 batch=100）
若业务要求连续自增，需设置
tdsql_auto_increment_batch_size=1（性能会下降）分区表：主键和所有唯一索引必须包含分区键，否则建表失败
表结构设计规范
单表列数建议不超过60（硬限制4096列）
单行数据建议不超过64KB（硬限制默认64MB，可调至512MB）
表名建议控制在32字符以内（硬限制64字符）
标识符（DB/Table/Column/Index）最大均为64字符
存储引擎统一为 RocksDB，建表时无论指定什么引擎都会被忽略
数量限制
项目 | 限制 |
单表最大列数 | 4096 |
单表最大索引数 | 64 |
单表最大分区数 | 8192 |
索引最大字节数 | 3072字节 |
索引最大列数 | 16列/索引 |
单行最大长度 | 默认64MB，最大512MB（参数 tdstore_txn_max_entry_size） |
最大建表数 | 与节点规格相关（1万~8万） |
分区表规范
分区策略选择
策略 | 适用场景 | 键类型 |
HASH | 均匀散列，整数键 | 整数类型 |
KEY | 均匀散列，字符串键 | 任意类型 |
RANGE | 时间范围、ID 区间查询 | 整数/日期 |
LIST | 枚举值分类（如地区） | 整数 |
分区键规范
主键和所有唯一索引必须包含分区键（违反则建表失败，这是最常见错误）
查询 WHERE 子句中必须携带分区键，否则会扫描所有分区（全分区扫描）
不要通过 UPDATE 修改分区键的值，会触发跨分区数据迁移，性能差且可能失败
分区数规划
推荐分区数 = 预期最大节点数 × 2
分区数过少会导致扩容时数据分布不均；过多增加管理开销
运行时修改分区定义可能需要做拷表 DDL，DDL 时长和 IO 开销随数据量增加
Partition Policy（数据分布策略）
-- 创建分布策略CREATE PARTITION POLICY policy_namePARTITION BY HASH(INT) PARTITIONS n;-- 建表时绑定CREATE TABLE t (...) PARTITION BY HASH(a) PARTITIONS n USING PARTITION POLICY policy_name;
支持将多张表的分区绑定在同一物理节点，减少分布式 Join 开销（适合关联查询频繁的表组）(目前支持 HASH 和 KEY 分区的一级分区表)
RANGE/RANGE COLUMNS 分区表可绑定时间调度 DP，实现冷数据自动归档（EXPIRE、START_TIME、END_TIME）只有未绑定任何数据对象的 DP 才能被修改或删除
单表转分区表
-- 支持在线转换，不阻塞读写ALTER TABLE t PARTITION BY HASH(id) PARTITIONS 16;
同步表规范
定义与场景
同步表写入时需强同步到所有有效 Follower 副本才返回，每个副本可提供强一致性读。
适用场景：
全局系统配置表、参数表
数据仓库维度表（如商品类目、地区字典）
TPCC item 表等读多写少的小表
不适用场景：
高频写入表（写性能受副本数影响，副本越多越慢）
大数据量表
创建语法
CREATE TABLE t (id BIGINT PRIMARY KEY,name VARCHAR(100)) SYNC_LEVEL = NODE(ALL) DISTRIBUTION = NODE(ALL);
SYNC_LEVEL = NODE(ALL) 和 DISTRIBUTION = NODE(ALL) 目前只支持 ALL，不能指定部分节点使用限制
不能是分区表（同步表与分区表互斥）
不支持属性转换：同步表不能转为普通表，反之亦然
任意 Follower 节点故障时，写请求会卡顿一个租约时间（lease 时间，约秒级）
广播同步日志流一旦创建不会被销毁，即使删除所有同步表
副本数量多时写性能线性下降，谨慎在大集群中使用
事务规范
隔离级别
支持：Read Committed (RC) 和 Repeatable Read (RR)，默认 RR
RR 实为快照隔离（Snapshot Isolation），不会出现幻读，但可能出现写偏斜（Write Skew）
RC 级别下与 MySQL 差异：TDSQL Boundless 在 RC 下仍可能使用范围锁（MySQL RC 不加间隙锁）
事务大小限制
限制项 | 默认值 | 参数 |
单行最大 | 64MB | tdstore_txn_max_entry_size |
单事务最大 | 1GB | tdstore_max_txn_size |
超出限制报错写入失败，批量操作必须有重试机制
事务数据在提交前完全缓存在内存中，大事务落盘功能尚在开发中
事务使用规范
-- 推荐开启方式（三种均支持）BEGIN;START TRANSACTION;SET autocommit = 0;
快照在第一条读写 SQL 执行时分配，不是 BEGIN 时
支持
SAVEPOINT 部分回滚支持悲观事务：
SELECT ... FOR UPDATE（排他锁）/ SELECT ... LOCK IN SHARE MODE（共享锁）锁机制注意事项
无索引的悲观锁会升级为范围锁，可能锁整表，务必确保查询条件有索引
锁基于逻辑键值而非物理存储，与 InnoDB 行为有差异
记录不存在时行为与 MySQL 不同，不会升级为间隙锁
需要避免的事务用法
避免超大事务：单事务不超过1GB，超大批量操作用
BATCH LIMIT 拆分XA 语法不生效：语法不报错但行为不符合 XA 语义，不要依赖 XA 实现分布式事务
不要长时间持有事务：可能导致 MVCC 版本积压，影响全局性能
避免无索引的 FOR UPDATE：极易导致全表范围锁
大批量删除
-- 使用 BATCH LIMIT 拆分大事务，每批原子，整体非原子BATCH LIMIT 2000 DELETE FROM t WHERE create_time < '2024-01-01';
限制：
仅支持 DELETE（不支持 UPDATE/INSERT）
不支持多表删除
不能在事务内嵌套使用
DELETE 语句不能含 ORDER BY 和 LIMIT
索引规范
索引创建
二级索引创建默认使用 Online DDL，不阻塞读写
推荐使用
ALGORITHM=INPLACE（默认）大表加索引建议在业务低峰期执行，并监控 INFORMATION_SCHEMA.DDL_JOBS
不支持的索引类型
FULLTEXT 全文索引（不支持）SPATIAL 空间索引（不支持）JSON 多值索引（不支持）降序索引（不支持）Online 方式添加/删除主键（不支持，需要 COPY 方式，会锁表）
索引限制
索引列最大3072字节
单索引最多16列
单表最多64个索引
DDL 操作规范
执行前检查
执行 DDL 前必须检查：
1. 确认存储空间充足（INPLACE DDL 需要临时空间）
2. 检查是否有慢查询或长事务
3. 查看数据分布是否均衡（严重倾斜时降低并行度）
4. 确认当前 CPU/IO 负载在合理范围
DDL 并行度控制
-- 数据倾斜时降低并行度（默认 8）SET max_parallel_ddl_degree = 4; -- 或 2-- 监控 DDL 进度SELECT * FROM information_schema.ddl_jobs WHERE state != 'done';
不支持 Online DDL 的操作（需锁表 COPY）
所有主键相关 DDL（Add/Drop Primary Key）
EXCHANGE PARTITIONANALYZE/CHECK PARTITION修改字符集（某些情况）
修改列类型（某些情况）
说明：
与 MySQL 8.0 差异：TDSQL Boundless 在
PARTITION BY、Converting charset、Changing column type 上支持 DML 并发，MySQL 不支持。与 MySQL 的重要差异（必知）
不支持功能列表
功能 | 是否支持 | 说明 |
外键 | ❌ | TDStore 限制，报错 |
FULLTEXT 索引 | ❌ | 报错1214 |
GIS/空间类型 | ❌ | 不支持 |
生成列 | ❌ | 不支持 |
XA 事务 | ⚠️ | 语法不报错但不生效 |
Event（事件调度器） | ❌ | 不支持 |
X 协议 | ❌ | 不支持 |
LOB 部分更新 | ❌ | 不支持 |
JSON 排序混合类型 | ❌ | 不支持 |
只读账号/只读节点 | ⚠️ | 计划后续支持 |
全局索引 | ❌ | 不支持 |
行为差异
存储引擎：统一强制 RocksDB，CREATE TABLE 中的 ENGINE= 被忽略。
自增列：全局唯一但不连续，高性能模式 batch=100。
网络访问：仅支持 VPC 内网，不支持公网访问。
SQL 编写规范
查询规范
分区表查询建议携带分区键在 WHERE 条件中，避免全分区扫描。
避免
SELECT *，明确列出所需字段。大范围查询（如全表扫描）建议添加
LIMIT 保护。使用
EXPLAIN 查看执行计划，确认分区裁剪（partition pruning）是否生效。写入规范
批量写入推荐使用
INSERT INTO ... VALUES (...),(...),...，减少网络往返。大批量写入考虑使用 Bulk Load 模式（
tdstore_bulk_load 参数），性能可提升数倍，详细请参见 关于数据导入（Bulk Load 模式）。避免在事务中混合大量读写操作，超过1GB事务大小限制会直接报错。
Failover 注意事项
应用层需实现重试逻辑，建议指数退避重试3次。
常见陷阱汇总
陷阱 | 说明 | 规避方法 |
写入热点 | 无主键或单调递增主键 | 使用复合主键或带散列前缀 |
唯一索引缺分区键 | 建表失败 | 所有唯一索引必须包含分区键 |
自增值不连续 | 缓存机制导致 | 业务不依赖自增连续性 |
XA 不生效 | 语法合法但无 XA 语义 | 改用 TDSQL Boundless 原生分布式事务 |
无索引 FOR UPDATE | 锁整表 | 确保查询条件有索引 |
大事务 OOM | 1GB内存限制 | 拆分事务，使用 BATCH LIMIT |
同步表写卡顿 | Follower 故障时卡一个 lease | 同步表只用于读多写少场景 |
Online DDL 加主键 | 不支持 Online，需锁表 | 建表时规划好主键 |
RC 下意外范围锁 | 与 MySQL RC 行为不同 | 关键业务实测验证锁行为 |
外键依赖 | 完全不支持 | 在应用层维护引用完整性 |
