StarRocks SMALLINT 类型详解：2 字节有符号整数的定义、建表与类型转换-二趣网

StarRocks SMALLINT 类型详解：2 字节有符号整数的定义、建表与类型转换

【免费下载链接】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

SMALLINT 是 StarRocks 中最基础的整数类型之一，以 2 字节存储有符号整数，取值范围为 [-32768, 32767]。本文围绕官方 SQL 参考文档展开，系统讲解 SMALLINT 的类型定义、建表与写入示例、底层存储实现，以及它在类型兼容与 schema 变更中的应用场景，帮助你在实际建表和数据建模中正确选型。

SMALLINT 类型定义与取值范围

根据 SMALLINT 官方文档，SMALLINT 是一个2 字节（16 位）的有符号整数，取值范围为 [-32768, 32767]。

存储大小：2 字节，即 16 bit。
有符号范围：最小值 -32768（即 -2^15），最大值 32767（即 2^15 - 1）。
典型适用场景：当业务数据的取值范围能稳定落在 2 字节有符号整数内时（例如小型状态码、枚举值、低基数分类编号等），使用 SMALLINT 相比 INT 可以节省一半存储空间，从而降低存储与扫描成本。

在 StarRocks 的完整整数类型家族中，SMALLINT 与其他整数类型的对比关系如下：

类型	存储字节数	取值范围	说明
TINYINT	1 字节	[-128, 127]	最小的有符号整数
SMALLINT	2 字节	[-32768, 32767]	本文主角，对应 MySQL 的 SHORT 类型
INT	4 字节	[-2147483648, 2147483647]	最常用的默认整数
BIGINT	8 字节	[-9223372036854775808, 9223372036854775807]	大范围整数
LARGEINT	16 字节	128 位有符号整数	超大范围整数

选型建议：先根据业务数值的真实边界确定最小可行类型，再预留一定的增长余量。SMALLINT 适合取值范围不大、且希望压缩存储的场景；若业务值可能突破 32767 或小于 -32768，则应升级为 INT。

建表与写入示例

官方文档给出了一个最简但完整的建表与写入示例，下面保留原文并补充注释说明：

CREATE TABLE smallintDemo ( pk SMALLINT COMMENT "range [-32768, 32767]" ) ENGINE=OLAP DUPLICATE KEY(pk) DISTRIBUTED BY HASH(pk) BUCKETS 1; INSERT INTO smallintDemo VALUES (32767);

执行查询后返回结果：

MySQL > SELECT * FROM smallintDemo; +-------+ | pk | +-------+ | 32767 | +-------+

要点说明：

该示例使用默认的ENGINE=OLAP，即 StarRocks 的内置 OLAP 引擎，并采用DUPLICATE KEY模型，适合无需去重、以明细数据为主的场景。
pk SMALLINT声明了主键列的数据类型为 SMALLINT，插入时写入的是最大值32767，验证了范围上界可用。
DISTRIBUTED BY HASH(pk) BUCKETS 1表示按主键哈希分桶，示例中仅使用 1 个桶，实际生产环境中应根据数据量与集群规模合理设置桶数。

边界值验证

由于 SMALLINT 是有符号类型，除上界 32767 外，还应关注下界 -32768。例如：

INSERT INTO smallintDemo VALUES (-32768);

两行数据分别代表上下边界，均可正常写入。若尝试写入超出范围的值（如32768或-32769），StarRocks 会因数值溢出而报错，这与所有定长整数类型的行为一致。

底层实现：从 FE 元数据到 BE 存储

SMALLINT 不仅仅是一个 SQL 层概念，它在 StarRocks 的整个执行链路上都有明确映射。

逻辑类型定义（BE 侧）

在 BE 的 logical_type.h 中，SMALLINT 被定义为逻辑类型枚举TYPE_SMALLINT = 3，注释明确标注其对应MYSQL_TYPE_SHORT，即与 MySQL 协议中的 SHORT 类型对齐：

TYPE_SMALLINT = 3, // MYSQL_TYPE_SHORT

同时，在该文件的辅助函数中，TYPE_SMALLINT被归入“整数类型”（integer types）集合，参与is_integer_type判断以及IntegerLTGuard、SumBigIntLTGuard等模板守卫，这意味着 SMALLINT 在表达式计算、谓词下推、聚合求和等场景中会被统一按整数语义处理。

FE 侧的类型兼容矩阵

在 FE 的 SchemaChangeTypeCompatibility.java 中，定义了 SMALLINT 与其他类型之间的 schema 变更兼容关系，从源码可以看出：

可转换为 SMALLINT 的来源类型：TINYINT（小类型可升级为 SMALLINT）；
SMALLINT 可升级成的目标类型：INT、BIGINT、LARGEINT、DOUBLE，以及 VARCHAR。

这构成了 StarRocks 类型演进的完整路径：TINYINT → SMALLINT → INT → BIGINT → LARGEINT，支持按需通过ALTER TABLE ... MODIFY COLUMN扩容列类型，同时 SMALLINT 也可直接转为 DOUBLE 或 VARCHAR。此外，同段代码中的ZONEMAP_REUSE_COMPATIBILITY_MATRIX表明，TINYINT 与 SMALLINT、SMALLINT 与 INT/BIGINT 之间保持 Zone Map（zonemap）复用兼容，即列类型升级后仍可复用原有统计信息，无需重建。

类型判断与列存储

在 BE 的 logical_type.h 中，TYPE_SMALLINT与TYPE_TINYINT、TYPE_INT、TYPE_BIGINT等一起被is_integer_type覆盖；在列式存储层（column/runtime_type_traits.h、column/storage_column_traits.h）中，SMALLINT 列以 2 字节定长方式编码存放，支持高效的向量化读写与压缩。

从源码结构看，SMALLINT 在 BE 中还贯穿于 Arrow 数据交换（arrow_to_starrocks_converter.cpp、column_to_arrow_converter.cpp）、类型转换（type_converter.cpp）与字典/变体编码（variant_encoder.cpp）等路径，说明它能够被外部数据源（如 Arrow/Parquet/ORC）正确导入导出。

SMALLINT 的常用操作

与其他数值类型的比较与计算

由于 SMALLINT 属于整数类型集合，它可以直接与 INT、BIGINT 等类型进行比较和四则运算，运算过程中 StarRocks 会自动进行类型提升，结果类型取决于表达式中最大的操作数类型。例如 SMALLINT 与 INT 相加，结果按 INT 计算，避免中间溢出。

在聚合与排序中的表现

SMALLINT 参与SUM、COUNT、AVG等聚合函数时，SumBigIntLTGuard等类型守卫会确保求和等操作提升到足够宽的结果类型，防止小整数在累加过程中溢出。

导入导出兼容性

SMALLINT 与标准 SQL 整数语义一致，可通过 Stream Load、Broker Load、INSERT INTO 等方式导入 CSV、Parquet、ORC 等格式的数据，导入时框架会按目标列类型自动完成字符串/数值到 SMALLINT 的转换，超界值将被拒绝或报错（取决于导入配置）。

总结

SMALLINT 是 StarRocks 整数类型体系中的 2 字节有符号整数，取值范围 [-32768, 32767]，适合对取值范围有明确边界的业务列使用。本文既覆盖了官方文档的建表与写入示例，也结合 BE 逻辑类型定义与 FE 类型兼容矩阵，说明了 SMALLINT 在存储、计算、导入导出和 schema 演进中的完整行为。实际建模时，建议结合业务数值边界、存储成本和未来扩展需求，在 TINYINT、SMALLINT、INT、BIGINT 之间做出合理选型。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析