StarRocks 系统限制与命名规范完整指南：对象命名、大小写敏感性、类型约束与关键参数

StarRocks 系统限制与命名规范完整指南：对象命名、大小写敏感性、类型约束与关键参数

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

本篇技术指南以 StarRocks 官方文档 System limits 为核心骨架，系统梳理在使用 StarRocks 时所有需要遵守的规则与限制，包括数据库、表、分区、列、索引等对象的命名规范与长度上限、标签命名规则、VARCHAR 长度演进、编码约束、表类型不可变性，以及enable_table_name_case_insensitive与expr_children_limit两个关键 FE 参数的底层实现。结合本仓库 FE/BE 源码，读者不仅能知道"哪些不能做"，还能理解"为什么不能做、源码层面如何强制"，从而在表结构设计、数据加载和 SQL 编写阶段提前规避兼容性陷阱。

一、连接协议与客户端版本要求

StarRocks 使用 MySQL 协议进行通信，你可以通过 MySQL 客户端或 JDBC 连接 StarRocks 集群。一个容易踩坑的细节是：建议使用 5.1 或更高版本的 MySQL 客户端。原因在于，早于 5.1 版本的 MySQL 客户端不支持长度超过 16 字符的用户名——如果你的用户名较长（StarRocks 允许用户名最长 128 字符，见下文），使用旧版客户端会导致连接失败。

二、对象命名规范

StarRocks 对 catalog、数据库、表、视图、异步物化视图、分区、列、索引、用户名、角色、仓库（repository）、资源（resource）、存储卷（storage volume）、管道（pipe）等对象统一适用以下命名规则。

2.1 字符集约束

对象名只能由以下字符组成：

• 数字（0-9）
• 字母（a-z 或 A-Z）
• 下划线（_）

其中有一个容易被忽略的特殊规则：用户名可以全部由数字组成（这是与其他对象命名的最大差异）。

2.2 起始字符

对象名必须以字母或下划线（_）开头，不能以数字开头。

2.3 长度上限

通用规则是名称不能超过 64 个字符，但不同类型有独立的上限：

从源码结构看，这些长度上限在 FE 侧的元数据管理与校验逻辑中统一下发，超出上限会在 DDL 阶段被直接拒绝，而不是在运行时才暴露问题。

2.4 大小写敏感性

列名（含列别名）、分区名和索引名不区分大小写，而其他名称（catalog、数据库、表、视图、用户名、角色等）区分大小写。这意味着SELECT * FROM mytable与SELECT * FROM MyTable会指向不同的表（在未开启大小写不敏感特性的前提下），而同一张表中的col_a与COL_A被视为同一列。

这一点直接影响表结构设计：在多团队协作或对接外部系统时，务必统一表名、库名的写法规范，避免因大小写不一致导致的"表不存在"类错误。

三、enable_table_name_case_insensitive：大小写不敏感特性深度解析

从 StarRocks 4.0 开始，FE 配置项enable_table_name_case_insensitive用于控制 catalog 名、数据库名、表名、视图名和异步物化视图名是否大小写不敏感。该特性的核心事实如下：

• 默认关闭（即上述名称默认大小写敏感）；
• 只能在创建集群时开启，集群启动后无法以任何方式修改。

3.1 源码级验证：为何"只能创建时开启"

该配置在 FE 中的定义位于 Config.java：

@ConfField(comment = "Enable case-insensitive catalog/database/table names. " + "Only configurable during cluster initialization, immutable once set.") public static boolean enable_table_name_case_insensitive = false;

注意该字段没有mutable = true标记，意味着它不属于可动态修改的配置。更关键的是 GlobalStateMgr.java 中的两个方法：

• initCaseInsensitive()：仅在集群首次初始化时被调用，将Config.enable_table_name_case_insensitive的值写入全局变量GlobalVariable.enableTableNameCaseInsensitive，一旦初始化失败直接System.exit(-1)；
• checkCaseInsensitive()：在集群启动时校验当前配置值与首次初始化时记录的值是否一致，不一致则记录错误日志并拒绝启动（同样调用System.exit(-1)）。

这两段逻辑从源码层面印证了文档中的警告：该配置在集群生命周期内是"一次定终身"的，任何修改尝试都会导致 FE 无法启动。

3.2 开启后的行为与代价

当该特性开启时，StarRocks 会将受影响的名称以小写形式存储，并在查询和写入（DDL/DML）处理过程中强制将所有 catalog、数据库、表、视图、物化视图名称转换为小写。这带来两个严重后果：

风险一：外部表和外部 catalog 可能不可用。不同的外部 catalog 服务遵循各自的命名与大小写约定。如果你的外部 schema、数据库或表名不是全小写，StarRocks 会在把 SQL 下推给连接器之前先将名称小写化，然后在数据源中查找一个并不存在的名称，导致查询以 "not found" 错误失败。

风险二：无法在集群创建后修改。如 3.1 节源码所示，修改该值会导致校验失败、FE 拒绝启动。

3.3 适用前提

文档给出的建议非常明确：强烈建议保持该特性关闭，除非你有充分且明确理解的理由。即使要开启，也只能在全新的集群上开启，并且必须确认你计划访问的所有对象名称（包括每个外部数据源中的对象名）已经是全小写。

3.4 测试用例佐证

仓库中的测试 TableObjectCaseInsensitiveTest.java 直接验证了该配置的不可变性：

• 执行admin set frontend config("enable_table_name_case_insensitive" = "false")会报错Config 'enable_table_name_case_insensitive' does not exist or is not mutable；
• 执行set global enable_table_name_case_insensitive = false会报错Variable 'enable_table_name_case_insensitive' is a read only variable。

也就是说，无论通过 Admin 命令还是全局变量方式，都无法在运行期改动该特性。

四、Label（标签）命名规范

在加载数据时，你可以为作业（job）指定标签（label）。标签命名规则为：

• 只能包含数字（0-9）、字母（a-z 或 A-Z）和下划线（_）；
• 可以以字母或下划线（_）开头；
• 长度不能超过 128 个字符。

标签是导入作业的幂等标识，合理命名标签（例如"数据源 + 日期 + 批次号"的格式）有助于在导入失败后精准定位与重试，同时规避重复导入。

五、数据类型与表结构限制

5.1 键列禁止使用 FLOAT / DOUBLE

创建表时，键列（key column）不能是 FLOAT 或 DOUBLE 类型。如果你需要用小数作为排序键或去重键，应使用 DECIMAL 类型来表示小数。这背后的原因从存储模型上可以推断：FLOAT/DOUBLE 是浮点类型，精度不可控，无法保证键的精确比较与去重语义，而 DECIMAL 是精确十进制类型，能提供确定性的排序与去重行为。

5.2 VARCHAR 最大长度随版本演进

VARCHAR 的最大长度在不同版本中差异巨大：

长度计算公式为：最大 VARCHAR 长度 = 最大行大小（1048578 字节） - 长度前缀（2 字节），其中长度前缀用于记录该值实际占用的字节数。

该限制在 BE 侧的源码中有直接对应。类型描述符 type_descriptor.h 中定义了：

static constexpr int MAX_VARCHAR_LENGTH = 1048576;

即 2.1 及以后版本中 VARCHAR 的硬上限 1 MB 正是由 BE 的类型系统常量直接约束的。此外要注意，VARCHAR 长度单位是字节而非字符数，因此如果数据中包含多字节 UTF-8 字符（如中文），实际可容纳的字符数会少于字节数。

5.3 仅支持 UTF-8 编码

StarRocks只支持 UTF-8 编码，不支持 GBK。这要求所有导入的数据、外部表读取的数据以及客户端连接所使用的字符集都遵循 UTF-8 规范。在对接遗留系统时，务必在数据链路的上游完成 GBK 到 UTF-8 的转码，否则可能出现乱码或导入失败。

5.4 表类型不可修改

StarRocks不支持修改已有表的表类型。例如，你不能将 Duplicate Key 表改为 Primary Key 表，反之亦然。如果确实需要变更表类型，只能创建新表并将数据迁移过去。因此在建表之初就应结合业务读写模式选对表模型：

• 明细查询/日志场景 → Duplicate Key 表；
• 去重/实时更新场景 → Primary Key 表；
• 聚合分析场景 → Aggregate Key 表；
• 主键频繁更新 + 部分列更新 → 可考虑 Unique Key 表或 Primary Key 表的相应更新模式。

六、查询深度限制：expr_children_limit

默认情况下，一个查询最多可嵌套10,000 个子查询，该上限由 FE 参数expr_children_limit控制。

6.1 源码实现

该参数定义在 Config.java：

/** * Limit on the number of expr children of an expr tree. */ @ConfField(mutable = true) public static int expr_children_limit = 10000;

注意它与enable_table_name_case_insensitive不同，标记了mutable = true，即该参数支持在线动态调整，可通过admin set frontend config("expr_children_limit" = "...")修改。

在解析阶段，该限制作用于表达式树（expr tree）的子节点数量上限。在 SqlParser.java 中可以找到实际应用逻辑：

int exprLimit = Math.max(Config.expr_children_limit, sessionVariable.getExprChildrenLimit());

即实际生效的上限取 FE 全局配置与会话变量中较大者，并通过PostProcessListener(tokenLimit, exprLimit)注入解析后处理流程。这意味着除了全局参数，你还可以通过会话级变量按连接进行更精细的调控。

6.2 实践建议

在正常业务场景下，10,000 层子查询嵌套几乎不会被触及。出现该限制报错通常意味着 SQL 由程序自动拼接生成（例如深度嵌套的 IN 子查询链），此时应优先改写 SQL 结构（如拆分为 JOIN 或临时表），而不是一味调大该参数，因为过深的表达式树会带来显著的解析与优化开销。

七、小结：一张表掌握 StarRocks 关键限制

本文所有规则与参数均可对照仓库源码验证：大小写特性与查询嵌套上限见 Config.java、GlobalStateMgr.java 与 SqlParser.java；VARCHAR 上限见 type_descriptor.h；大小写不可变性测试见 TableObjectCaseInsensitiveTest.java。在设计表结构、编写 DDL/DML 或对接外部数据源之前，对照本文清单做一次系统性检查，可以最大程度避免因命名、编码或类型约束导致的返工。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks