数据类型

Lakehouse 支持数值、字符串、时间、布尔、二进制及复杂类型（ARRAY、MAP、STRUCT、JSON、VECTOR、BITMAP）。

类型速查表

数值类型

类型	存储	范围 / 精度	典型用法
`TINYINT` TINYINT	1 字节	-128 ~ 127	状态码、枚举值
`SMALLINT` SMALLINT	2 字节	-32,768 ~ 32,767	小范围整数
`INT` INT	4 字节	-2,147,483,648 ~ 2,147,483,647	通用整数 ID
`BIGINT` BIGINT	8 字节	-9.2×10¹⁸ ~ 9.2×10¹⁸	大整数、时间戳毫秒
`FLOAT` FLOAT	4 字节	约 7 位有效数字	近似浮点
`DOUBLE` DOUBLE	8 字节	约 15 位有效数字	高精度浮点
`DECIMAL(p, s)` DECIMAL(p, s)	可变	最大精度 p=38，小数位 s	金额、精确计算，如 `DECIMAL(18, 4)` DECIMAL(18, 4)

字符串类型

类型	最大长度	说明
`STRING` STRING	16 MB	无长度限制，推荐默认使用
`VARCHAR(n)` VARCHAR(n)	n ≤ 1,048,576 字符	有长度约束，超出静默截断
`CHAR(n)` CHAR(n)	n ≤ 255 字符	定长，不补空格

时间类型

类型	格式	说明
`DATE` DATE	`YYYY-MM-DD` YYYY-MM-DD	仅日期，无时间
`TIMESTAMP` TIMESTAMP	`YYYY-MM-DD HH:MM:SS` YYYY-MM-DD HH:MM:SS	带本地时区（等同 `TIMESTAMP_LTZ` TIMESTAMP_LTZ ）
`TIMESTAMP_NTZ` TIMESTAMP_NTZ	`YYYY-MM-DD HH:MM:SS` YYYY-MM-DD HH:MM:SS	不含时区信息，存储原始时间值

⚠️ 从 PostgreSQL 迁移时注意：PostgreSQL 的

TIMESTAMP

TIMESTAMP

（无时区）对应 Lakehouse 的

TIMESTAMP_NTZ

TIMESTAMP_NTZ

，详见下方说明。

布尔与二进制类型

类型说明

类型	说明
`BOOLEAN` BOOLEAN	`true` true / `false` false
`BINARY` BINARY	固定长度二进制字符串

BOOLEAN

BOOLEAN

true

true

false

false

BINARY

BINARY

固定长度二进制字符串

复杂类型

类型	语法示例	说明
`ARRAY` ARRAY	`ARRAY<INT>` ARRAY<INT> 、 `ARRAY<STRING>` ARRAY<STRING>	同类型元素的有序集合
`MAP` MAP	`MAP<STRING, INT>` MAP<STRING, INT>	键值对，键类型必须相同
`STRUCT` STRUCT	`STRUCT<name:STRING, age:INT>` STRUCT<name:STRING, age:INT>	多字段记录，字段类型可不同
`JSON` JSON	`JSON` JSON	存储任意 JSON 结构，支持动态字段访问
`VECTOR` VECTOR	`VECTOR(FLOAT, 1024)` VECTOR(FLOAT, 1024)	固定维度数值向量，用于 AI 嵌入向量存储
`BITMAP` BITMAP	`BITMAP` BITMAP	位图，用于高效基数统计（UV 计算等）

复杂类型示例：

CREATE TABLE example ( tags ARRAY<STRING>, attributes MAP<STRING, STRING>, address STRUCT<city:STRING, zip:STRING>, metadata JSON, embedding VECTOR(FLOAT, 1536), user_bitmap BITMAP );

Lakehouse 支持多个类型别名，主要用于兼容从其他数据库（MySQL、PostgreSQL、Hive 等）迁移过来的 DDL 和 SQL 脚本，无需手动替换类型名即可直接执行。

别名	规范类型
`BYTE` BYTE	`TINYINT` TINYINT
`SHORT` SHORT	`SMALLINT` SMALLINT
`INTEGER` INTEGER	`INT` INT
`LONG` LONG	`BIGINT` BIGINT
`REAL` REAL	`FLOAT` FLOAT
`NUMERIC(p, s)` NUMERIC(p, s)	`DECIMAL(p, s)` DECIMAL(p, s)
`TEXT` TEXT	`STRING` STRING
`TIMESTAMP` TIMESTAMP	`TIMESTAMP_LTZ` TIMESTAMP_LTZ

别名的转换时机与可见性

别名在 SQL 解析阶段立即转换为规范类型，系统不保留原始别名信息。转换完成后，别名与规范类型在任何地方均无法区分：

```
DESCRIBE
```
DESCRIBE
显示规范类型名
```
SHOW CREATE TABLE
```
SHOW CREATE TABLE
输出规范类型名
```
typeof()
```
typeof()
返回规范类型名
没有任何系统视图或元数据记录原始别名

这意味着：用

REAL

REAL

建的列，

DESCRIBE

DESCRIBE

显示

float

float

；用

INTEGER

INTEGER

建的列，

SHOW CREATE TABLE

SHOW CREATE TABLE

输出

int

int

。这是正常行为，不是类型被修改。

⚠️ 从 Lakehouse 导出 DDL 再导入时，别名会被替换为规范名，导出脚本与原始建表脚本的类型名不一致。如果需要保持脚本一致性，建表时直接使用规范类型名。

示例：用别名建表后系统的实际显示

用 MySQL 迁移过来的 DDL 直接执行：

CREATE TABLE orders ( id INTEGER, amount NUMERIC(18, 4), status TEXT, created TIMESTAMP );

DESCRIBE

DESCRIBE

显示的是规范类型名，不是建表时使用的别名：

DESCRIBE orders;

SHOW CREATE TABLE

SHOW CREATE TABLE

同样输出规范名：

SHOW CREATE TABLE orders; -- CREATE TABLE orders (id int, amount decimal(18,4), status string, created timestamp_ltz) ...

表的实际行为与用规范类型名建表完全相同，类型并未被修改。

VARCHAR/CHAR 与 STRING 的关系

Lakehouse 同时支持

VARCHAR(n)

VARCHAR(n)

、

CHAR(n)

CHAR(n)

和

STRING

STRING

三种字符串类型，但它们是相互独立的类型，不是别名关系：

类型	特点	`typeof()` typeof() 返回
`STRING` STRING	无长度限制，最大 16 MB	`string` string
`VARCHAR(n)` VARCHAR(n)	最大 n 个字符（n ≤ 1048576）	`varchar(n)` varchar(n)
`CHAR(n)` CHAR(n)	最大 n 个字符（n ≤ 255），不补空格	`char(n)` char(n)

从 MySQL 迁移时，

VARCHAR(n)

VARCHAR(n)

和

CHAR(n)

CHAR(n)

的 DDL 可以直接使用，行为与 MySQL 的主要差异：

三种类型均不补空格，
```
CHAR(10)
```
CHAR(10)
存入
```
'abc'
```
'abc'
，
```
LENGTH
```
LENGTH
返回
```
3
```
3
超出声明长度的字符串静默截断，不报错
比较按实际内容比较，不存在尾随空格忽略逻辑

如果迁移时不需要保留长度约束，可以统一用

STRING

STRING

替代

VARCHAR(n)

VARCHAR(n)

，减少截断风险。

TIMESTAMP 默认带时区

Lakehouse 的

TIMESTAMP

TIMESTAMP

等同于

TIMESTAMP_LTZ

TIMESTAMP_LTZ

（本地时区），这与 MySQL 的

TIMESTAMP

TIMESTAMP

行为类似，但与 PostgreSQL 的

TIMESTAMP

TIMESTAMP

（无时区）不同。

从 PostgreSQL 迁移时需要注意：

来源	对应 Lakehouse 类型
PostgreSQL `TIMESTAMP` TIMESTAMP （无时区）	`TIMESTAMP_NTZ` TIMESTAMP_NTZ
PostgreSQL `TIMESTAMPTZ` TIMESTAMPTZ	`TIMESTAMP` TIMESTAMP （即 `TIMESTAMP_LTZ` TIMESTAMP_LTZ ）
MySQL `TIMESTAMP` TIMESTAMP	`TIMESTAMP` TIMESTAMP （即 `TIMESTAMP_LTZ` TIMESTAMP_LTZ ）
MySQL `DATETIME` DATETIME	`TIMESTAMP_NTZ` TIMESTAMP_NTZ

直接将 PostgreSQL 的

TIMESTAMP

TIMESTAMP

类型 DDL 迁移到 Lakehouse，列会变成带时区的

TIMESTAMP_LTZ

TIMESTAMP_LTZ

，写入和读取结果会受会话时区影响，与原库行为不一致。

宽松模式：类型错误默认返回 NULL

Lakehouse 默认运行在宽松模式（lenient mode）。类型转换失败、数值溢出等错误不抛异常，返回 NULL。这与大多数数据库的默认行为不同：

场景	多数数据库	Lakehouse 默认
`CAST('abc' AS INT)` CAST('abc' AS INT)	报错	`NULL` NULL
`CAST(200 AS TINYINT)` CAST(200 AS TINYINT) （溢出）	报错	`NULL` NULL
`CAST('2023-02-29' AS DATE)` CAST('2023-02-29' AS DATE) （非法日期）	报错	`NULL` NULL
UNION ALL 中混合类型转换失败	报错	`NULL` NULL

宽松模式的好处是 ETL 管道不会因单行数据问题中断；代价是错误被静默吞掉，数据质量问题难以发现。

可通过以下方式调整行为：

-- 开启严格模式，转换失败直接报错 SET cz.sql.cast.mode = strict; -- 或使用 TRY_CAST，失败时返回 NULL（与宽松模式一致，但意图明确） SELECT TRY_CAST('abc' AS INT);

从其他数据库迁移时，如果原有 SQL 依赖类型错误报错来发现数据问题，迁移到 Lakehouse 后建议在关键 ETL 节点加入显式的 NULL 检查，或开启严格模式。

文档	说明
数据类型转化	各类型之间的隐式和显式转换规则
类型转化函数	CAST、TRY_CAST、类型转换函数参考
TIMESTAMP_NTZ	无时区时间戳的详细说明和使用场景
VECTOR 类型	向量类型的语法、维度配置和使用示例
BITMAP 类型	位图类型的使用场景和函数参考
数据类型转换指南	从 MySQL / PostgreSQL / Hive 迁移时的类型对照
CREATE TABLE	建表时使用各数据类型的完整语法

文档	说明
分区与分桶	按时间或业务字段分区，提升查询裁剪效率
分桶（CLUSTERED BY）	按字段哈希分桶，提升 Join 和聚合性能
主键	主键表设计，支持 CDC 实时写入去重
唯一键	声明式 UNIQUE 约束，用于查询优化
推荐表的排序列	通过排序列加速范围查询和过滤
Bloomfilter 索引	等值查询加速，跳过不含目标值的数据文件
倒排索引	全文检索加速，支持中英文分词
向量索引	ANN 近似最近邻检索，适合语义搜索和 RAG
表设计最佳实践	分区、分桶、索引的综合选型建议

数据类型

类型速查表

数值类型

字符串类型

时间类型

布尔与二进制类型

复杂类型

VARCHAR/CHAR 与 STRING 的关系

TIMESTAMP 默认带时区

宽松模式：类型错误默认返回 NULL

相关文档