TDengine 命名规范与系统限制全解析标识符规则、密码字符集与容量上限【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengineTDengine 作为面向工业物联网IIoT场景的高性能时序数据库其标识符命名、密码设置与各类资源上限直接决定了表结构设计和 SQL 使用方式。本文以官方文档 Naming Conventions and Limitations 为核心结合仓库中的头文件宏定义与配置解析源码系统梳理库名、表名、列名、标签名的命名规则密码合法字符集以及行大小、列数、标签数、SQL 长度等硬性限制帮助你在建库建表、账号管理和 SQL 编写时避开边界陷阱。一、命名规则Naming RulesTDengine 中的数据库名、表名、列名、标签名等标识符遵循统一的命名规则同时在 3.x 版本中通过反引号转义机制提供了更大的灵活性。1.1 基础规则合法字符标识符只能由英文字母、数字和下划线_组成。起始字符允许以英文字母或下划线开头不允许以数字开头。大小写不敏感TDengine 对标识符不区分大小写abc、ABC、aBc在未转义时视为同一个名称。保留字限制标识符不能使用 保留关键字。从源码定义看标识符的长度上限在仓库中有对应的宏约束例如表名与数据库名的缓冲区长度的定义位于 include/util/tdef.h#define TSDB_TABLE_NAME_LEN 193 // 192 字节表名 1 字节 \0 终止符 #define TSDB_DB_NAME_LEN 65 // 64 字节库名 1 字节 \0 终止符也就是说表名最大长度为 192 字节不含库名前缀与分隔符数据库名最大长度为 64 字节这与本文后续通用限制一节中的描述完全一致。1.2 反引号转义规则为了支持更多形式的表列名TDengine 引入了反引号作为转义字符。使用反引号包裹后的名称遵循以下特殊规则保留大小写转义字符内的内容不做大小写统一用户指定的大小写会被原样保留。例如aBc与abc是两个不同的表列名而未转义的abc与aBc则是同一个表列名。支持非常规字符可以创建包含字母、数字、下划线以外字符的表列名例如abcTD。但转义后的名称仍然不能包含.否则会报错The table name cannot contain .点号被用于库名与表名之间的分隔。支持数字开头可以创建以数字开头的表列名例如1970。支持保留字可以使用保留关键字作为表列名例如select。这一机制非常适合对接外部系统同步数据时出现的特殊表名以及在时序数据建模中需要直接使用数字或保留字作为列名的场景。二、密码合法字符集TDengine 对用户密码使用的字符集有明确规定。合法的密码字符集为[a-zA-Z0-9!?$%^*()_-{[}]:;~#|,.?/]禁止出现的字符单引号、双引号、反引号、反斜杠\以及空格。这一限制用于避免密码中的特殊字符与 SQL 解析、连接字符串配置产生歧义。密码长度方面文档规定用户密码长度范围为8–255 字节详见下文通用限制。三、通用限制General Restrictions本节汇总 TDengine 在标识符长度、数据规模、SQL 语句等方面的全部容量上限并给出仓库源码中的对应依据。限制项上限值说明数据库名最大长度64 字节对应源码TSDB_DB_NAME_LEN 65含\0表名最大长度192 字节不含库名前缀与分隔符源码TSDB_TABLE_NAME_LEN 193含\0每行数据最大长度48KB3.0.5.0 起为 64KB行内每个 BINARY/NCHAR 类型列额外占用 2 字节存储空间列名最大长度64 字节—单表最大列数4096 列最少 2 列第一列必须为时间戳标签名最大长度64 字节—单表最大标签数128 个至少 1 个标签单表标签值总长度不超过 16KBSQL 语句默认最大长度4194304 字符可通过maxSQLLength参数配置上限 64MBSELECT 结果最大列数4096 列语句中的函数调用也会占用列空间数据库/超级表/表数量无系统限制仅受系统资源约束数据库副本数只能为 1 或 3—用户名最大长度23 字节对应源码TSDB_USER_LEN TSDB_UNI_LEN 24含\0用户密码长度8–255 字节—数据行总数取决于可用资源无固定上限单数据库最大 vgroup 数1024—3.1 列数与标签数上限的源码依据在 include/util/tdef.h 中列数的宏定义区分了普通表与虚拟表virtual table#define TSDB_MAX_COLUMNS 32767 #define TSDB_MAX_COLUMNS_NON_VIRTUAL 4096TSDB_MAX_COLUMNS_NON_VIRTUAL 4096对应普通表 4096 列的上限即文档所述最大 4096 列TSDB_MAX_COLUMNS 32767用于虚拟表如流计算、视图场景的列数上限。标签相关的宏定义同样位于 include/util/tdef.h#define TSDB_MAX_TAGS_LEN 16384 // 单表标签值总长度上限 16KB #define TSDB_MAX_TAGS 128 // 单表最大标签数 128TSDB_MAX_TAGS_LEN 16384正好对应文档中标签值总长度不超过 16KB的限制TSDB_MAX_TAGS 128对应最多 128 个标签。这两组宏在服务端建表校验中被实际引用例如 source/common/src/msg/tmsg.c 中会对标签数与列数进行合法性检查if (numOfTags 0 || numOfTags TSDB_MAX_TAGS || numOfColumns 0 || numOfColumns TSDB_MAX_COLUMNS || ...)3.2 SQL 长度限制与 maxSQLLength 参数SQL 语句默认最大长度为 4,194,304 字符即 4MB可以通过maxSQLLength参数调整最大可配置为 64MB。该参数的底层实现在 source/common/src/tglobal.cTAOS_CHECK_RETURN(cfgAddInt32(pCfg, maxSQLLength, tsMaxSQLLength, 1024 * 1024, 64 * 1024 * 1024, CFG_SCOPE_CLIENT, CFG_DYN_CLIENT, CFG_CATEGORY_LOCAL, CFG_PRIV_SYSTEM));默认值tsMaxSQLLength 4 * 1024 * 10244 MiB定义于 source/common/src/tglobal.c最小值 1MB、最大值 64MB由cfgAddInt32的参数区间强制约束CFG_SCOPE_CLIENT表明这是一个客户端侧配置可通过客户端配置文件如 taos.cfg设置并支持客户端运行期动态调整CFG_DYN_CLIENT。也就是说当你需要提交大批量 INSERT、超长 SQL 或大型 UDF 创建语句时若提示 SQL 长度超限可在客户端配置文件中调大maxSQLLength但最高不能超过 64MB。3.3 行长度与 BINARY/NCHAR 的额外开销每行数据最大长度为 48KB3.0.5.0 版本起为 64KB。需要注意的是行内每个BINARY/NCHAR类型列在数据行中还会额外占用 2 字节的存储空间用于记录长度等信息因此实际可用载荷需要为每个变长列预留这部分开销。在设计宽表时应结合列数≤4096与单行字节数≤64KB双重约束进行估算。3.4 其他关键限制说明最少 2 列且首列为时间戳每张表至少包含一个时间戳列主键和一个数据列时间戳必须位于第一列这是 TDengine 时序模型的基本要求。副本数仅支持 1 或 3数据库创建时replica参数只能设置为 1 或 3不支持 2 副本或更高配置这与内置 Raft 一致性协议的典型部署形态单机 1 副本、集群 3 副本一致。vgroup 上限 1024单个数据库最多可划分 1024 个 vgroup虚拟数据组。当数据量或节点规模较大时需要注意 vgroup 数不会自动超过该上限数据分布策略应在此范围内规划。资源决定规模数据库、超级表、普通表的数量以及数据行总数不受系统固定限制仅受内存、磁盘等系统资源约束因此不存在建多少张表的硬性瓶颈。四、实践建议命名规范先行生产环境中建议统一使用小写字母 下划线的命名风格避免依赖反引号转义来补救特殊名称仅在对接外部系统、必须使用数字开头或保留字时才使用反引号。规避点号冲突即使使用反引号标识符中也不能出现.因为点号被 TDengine 用作库名与表名及全限定名的分隔符转义也无法绕开该限制。宽表设计需算总账在规划列数接近 4096 的宽表、或单行包含大量 BINARY/NCHAR 列时需同时核算列数上限单行 64KB 上限以及变长列每列 2 字节的额外开销。标签总量控制标签值总长度不超过 16KB、数量不超过 128 个。标签是静态元数据频繁变化的业务属性应建模为数据列而非标签。密码设置遵守字符集不要在密码中使用引号、反斜杠或空格长度保持在 8–255 字节之间否则创建用户会失败。按需调整 maxSQLLength默认 4MB 的 SQL 长度对常规操作足够仅在确有超长 SQL 需求时于客户端侧调大该参数且注意上限为 64MB。如需查阅保留字完整清单可参见 保留关键字文档本限制文档的英文原文位于 docs/en/05-tdengine-sql/11-appendix/02-limit.md对应的中文版本见 docs/zh/05-tdengine-sql/11-appendix/02-limit.md。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考