数据类型兼容性参考

将现有数据库的 DDL 和 SQL 迁移到 Lakehouse 时，本文列出常见的兼容性差异点，帮助提前规避问题。

数据类型映射

Lakehouse 支持多种类型别名，来自其他数据库的 DDL 可以直接使用，无需手动替换类型名。别名在解析时立即转换为 Lakehouse 的规范类型，

DESCRIBE

DESCRIBE

和

SHOW CREATE TABLE

SHOW CREATE TABLE

显示的是规范名，不是原始别名。

MySQL

MySQL 类型	Lakehouse 类型	说明
`TINYINT` TINYINT	`TINYINT` TINYINT	直接支持
`SMALLINT` SMALLINT	`SMALLINT` SMALLINT	直接支持
`INT` INT / `INTEGER` INTEGER	`INT` INT	直接支持， `INTEGER` INTEGER 为别名
`BIGINT` BIGINT	`BIGINT` BIGINT	直接支持
`FLOAT` FLOAT	`FLOAT` FLOAT	直接支持
`DOUBLE` DOUBLE	`DOUBLE` DOUBLE	直接支持
`DECIMAL(p,s)` DECIMAL(p,s) / `NUMERIC(p,s)` NUMERIC(p,s)	`DECIMAL(p,s)` DECIMAL(p,s)	直接支持， `NUMERIC` NUMERIC 为别名
`VARCHAR(n)` VARCHAR(n)	`VARCHAR(n)` VARCHAR(n)	直接支持，最大长度 1048576
`CHAR(n)` CHAR(n)	`CHAR(n)` CHAR(n)	直接支持，最大长度 255
`TEXT` TEXT	`STRING` STRING	直接支持， `TEXT` TEXT 为别名
`DATE` DATE	`DATE` DATE	直接支持
`DATETIME` DATETIME	`TIMESTAMP_NTZ` TIMESTAMP_NTZ	MySQL DATETIME 无时区，对应 TIMESTAMP_NTZ
`TIMESTAMP` TIMESTAMP	`TIMESTAMP` TIMESTAMP （即 `TIMESTAMP_LTZ` TIMESTAMP_LTZ ）	两者均为带时区时间戳
`BOOLEAN` BOOLEAN / `BOOL` BOOL	`BOOLEAN` BOOLEAN	直接支持； `BOOL` BOOL 别名不支持，需改为 `BOOLEAN` BOOLEAN

⚠️ MySQL 的

DATETIME

DATETIME

应映射为

TIMESTAMP_NTZ

TIMESTAMP_NTZ

，而非

TIMESTAMP

TIMESTAMP

。若误用

TIMESTAMP

TIMESTAMP

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

PostgreSQL

PostgreSQL 类型	Lakehouse 类型	说明
`SMALLINT` SMALLINT / `INT2` INT2	`SMALLINT` SMALLINT	`INT2` INT2 别名不支持，需改为 `SMALLINT` SMALLINT 或 `SHORT` SHORT
`INTEGER` INTEGER / `INT4` INT4	`INT` INT	`INT4` INT4 别名不支持，需改为 `INT` INT 或 `INTEGER` INTEGER
`BIGINT` BIGINT / `INT8` INT8	`BIGINT` BIGINT	`INT8` INT8 别名不支持，需改为 `BIGINT` BIGINT 或 `LONG` LONG
`REAL` REAL / `FLOAT4` FLOAT4	`FLOAT` FLOAT	`REAL` REAL 支持； `FLOAT4` FLOAT4 不支持，需改为 `FLOAT` FLOAT
`DOUBLE PRECISION` DOUBLE PRECISION / `FLOAT8` FLOAT8	`DOUBLE` DOUBLE	`FLOAT8` FLOAT8 不支持，需改为 `DOUBLE` DOUBLE
`NUMERIC(p,s)` NUMERIC(p,s) / `DECIMAL(p,s)` DECIMAL(p,s)	`DECIMAL(p,s)` DECIMAL(p,s)	直接支持
`VARCHAR(n)` VARCHAR(n)	`VARCHAR(n)` VARCHAR(n)	直接支持
`CHAR(n)` CHAR(n)	`CHAR(n)` CHAR(n)	直接支持
`TEXT` TEXT	`STRING` STRING	直接支持， `TEXT` TEXT 为别名
`DATE` DATE	`DATE` DATE	直接支持
`TIMESTAMP` TIMESTAMP （无时区）	`TIMESTAMP_NTZ` TIMESTAMP_NTZ	PostgreSQL 默认 TIMESTAMP 无时区
`TIMESTAMPTZ` TIMESTAMPTZ	`TIMESTAMP` TIMESTAMP （即 `TIMESTAMP_LTZ` TIMESTAMP_LTZ ）	带时区时间戳
`BOOLEAN` BOOLEAN	`BOOLEAN` BOOLEAN	直接支持
`BYTEA` BYTEA	`BINARY` BINARY	二进制类型，需手动替换

⚠️ PostgreSQL 的

TIMESTAMP

TIMESTAMP

（无时区）应映射为

TIMESTAMP_NTZ

TIMESTAMP_NTZ

。直接迁移到 Lakehouse 的

TIMESTAMP

TIMESTAMP

会变成带时区类型，行为不同。

Hive

Hive 类型	Lakehouse 类型	说明
`TINYINT` TINYINT	`TINYINT` TINYINT	直接支持
`SMALLINT` SMALLINT	`SMALLINT` SMALLINT	直接支持
`INT` INT	`INT` INT	直接支持
`BIGINT` BIGINT	`BIGINT` BIGINT	直接支持
`FLOAT` FLOAT	`FLOAT` FLOAT	直接支持
`DOUBLE` DOUBLE	`DOUBLE` DOUBLE	直接支持
`DECIMAL(p,s)` DECIMAL(p,s)	`DECIMAL(p,s)` DECIMAL(p,s)	直接支持
`STRING` STRING	`STRING` STRING	直接支持
`VARCHAR(n)` VARCHAR(n)	`VARCHAR(n)` VARCHAR(n)	直接支持
`CHAR(n)` CHAR(n)	`CHAR(n)` CHAR(n)	直接支持
`DATE` DATE	`DATE` DATE	直接支持
`TIMESTAMP` TIMESTAMP	`TIMESTAMP_NTZ` TIMESTAMP_NTZ	Hive TIMESTAMP 无时区语义
`BOOLEAN` BOOLEAN	`BOOLEAN` BOOLEAN	直接支持
`BINARY` BINARY	`BINARY` BINARY	直接支持
`ARRAY<T>` ARRAY<T>	`ARRAY<T>` ARRAY<T>	直接支持
`MAP<K,V>` MAP<K,V>	`MAP<K,V>` MAP<K,V>	直接支持
`STRUCT<...>` STRUCT<...>	`STRUCT<...>` STRUCT<...>	直接支持

Spark SQL

Spark 类型	Lakehouse 类型	说明
`BooleanType` BooleanType	`BOOLEAN` BOOLEAN	直接支持
`ByteType` ByteType	`TINYINT` TINYINT	Spark Byte 对应 Lakehouse TINYINT
`ShortType` ShortType	`SMALLINT` SMALLINT	直接支持
`IntegerType` IntegerType	`INT` INT	直接支持
`LongType` LongType	`BIGINT` BIGINT	直接支持
`FloatType` FloatType	`FLOAT` FLOAT	直接支持
`DoubleType` DoubleType	`DOUBLE` DOUBLE	直接支持
`DecimalType` DecimalType	`DECIMAL(p,s)` DECIMAL(p,s)	直接支持
`StringType` StringType	`STRING` STRING	直接支持
`BinaryType` BinaryType	`BINARY` BINARY	直接支持
`DateType` DateType	`DATE` DATE	直接支持
`TimestampType` TimestampType	`TIMESTAMP_LTZ` TIMESTAMP_LTZ	Spark 默认带时区
`TimestampNTZType` TimestampNTZType	`TIMESTAMP_NTZ` TIMESTAMP_NTZ	Spark 3.4+ 新增无时区类型
`ArrayType` ArrayType	`ARRAY<T>` ARRAY<T>	直接支持
`MapType` MapType	`MAP<K,V>` MAP<K,V>	直接支持
`StructType` StructType	`STRUCT<...>` STRUCT<...>	直接支持

⚠️ Spark 的

TimestampType

TimestampType

默认带时区，对应 Lakehouse 的

TIMESTAMP_LTZ

TIMESTAMP_LTZ

。若 Spark 代码中使用

TimestampNTZType

TimestampNTZType

，应映射为

TIMESTAMP_NTZ

TIMESTAMP_NTZ

。

⚠️ 通过 Spark Connector 写入 Lakehouse 时，必须全字段写入，不支持部分字段写入；且不支持主键表（PK 表）写入。

行为差异

类型转换失败的处理方式

场景	MySQL / PostgreSQL	Spark SQL	Lakehouse 默认
`CAST('abc' AS INT)` CAST('abc' AS INT)	报错	返回 `NULL` NULL	返回 `NULL` NULL
数值溢出（如 `CAST(200 AS TINYINT)` CAST(200 AS TINYINT) ）	报错	返回 `NULL` NULL	返回 `NULL` NULL
非法日期（如 `CAST('2023-02-29' AS DATE)` CAST('2023-02-29' AS DATE) ）	报错	返回 `NULL` NULL	返回 `NULL` NULL

Lakehouse 默认运行在宽松模式，行为与 Spark SQL 一致：转换失败不报错，静默返回 NULL。从 MySQL/PostgreSQL 等严格模式数据库迁移时，需要在 ETL 关键节点加入显式 NULL 检查，或开启严格模式：

SET cz.sql.cast.mode = strict;

CHAR 不补空格

MySQL 和标准 SQL 的

CHAR(n)

CHAR(n)

会用空格将短字符串填充至 n 位，Lakehouse 不补空格。

LENGTH(CAST('abc' AS CHAR(10)))

LENGTH(CAST('abc' AS CHAR(10)))

，不是

。

比较时也按实际内容比较，

'abc' = 'abc  '

'abc' = 'abc '

false

false

。

VARCHAR/CHAR 超长静默截断

超出声明长度的字符串写入时静默截断，不报错。从有严格长度校验的数据库迁移时，建议在应用层保留长度校验逻辑。

INSERT VALUES 中字符串不隐式转为日期类型

在

INSERT VALUES

INSERT VALUES

中，字符串不会隐式转换为

DATE

DATE

、

TIMESTAMP

TIMESTAMP

、

TIMESTAMP_NTZ

TIMESTAMP_NTZ

，需要显式声明类型：

-- 报错 INSERT INTO t(dt) VALUES ('2024-01-15'); -- 正确 INSERT INTO t(dt) VALUES (DATE'2024-01-15'); INSERT INTO t(dt) VALUES (CAST('2024-01-15' AS DATE));

SELECT

SELECT

中字符串可以隐式匹配日期列，只有

INSERT VALUES

INSERT VALUES

有此限制。

NOT IN 包含 NULL

v NOT IN (1, NULL)

v NOT IN (1, NULL)

在三值逻辑下永远返回

NULL

NULL

（而非

true

true

或

false

false

），导致过滤条件失效。这与 MySQL、PostgreSQL 和 Spark SQL 行为一致，但容易被忽略：

-- 以下查询永远返回空结果，因为子查询可能包含 NULL SELECT * FROM t WHERE id NOT IN (SELECT id FROM other); -- 安全写法 SELECT * FROM t WHERE NOT EXISTS (SELECT 1 FROM other WHERE other.id = t.id);

Spark SQL 兼容性说明

Spark SQL 与 Lakehouse 在类型转换行为上高度一致（宽松模式下均返回 NULL）。完整的 Spark SQL 迁移指南（含建表语法、JSON 处理、窗口函数、LATERAL VIEW、配置映射等）详见 Spark SQL 迁移指南。

核心注意事项：

```
TimestampType
```
TimestampType
→
```
TIMESTAMP_LTZ
```
TIMESTAMP_LTZ
，
```
TimestampNTZType
```
TimestampNTZType
→
```
TIMESTAMP_NTZ
```
TIMESTAMP_NTZ
DataFrame 写入必须全字段，不支持 PK 表
函数兼容性良好，40+ 常用函数完全支持

不支持的别名

以下别名在其他数据库中常见，但 Lakehouse 不支持，迁移时需手动替换：

不支持的写法	替换为	来源
`BOOL` BOOL	`BOOLEAN` BOOLEAN	MySQL
`INT2` INT2	`SMALLINT` SMALLINT	PostgreSQL
`INT4` INT4	`INT` INT	PostgreSQL
`INT8` INT8	`BIGINT` BIGINT	PostgreSQL
`FLOAT4` FLOAT4	`FLOAT` FLOAT	PostgreSQL
`FLOAT8` FLOAT8	`DOUBLE` DOUBLE	PostgreSQL
`NUMBER(p,s)` NUMBER(p,s)	`DECIMAL(p,s)` DECIMAL(p,s)	Oracle
`DOUBLE PRECISION` DOUBLE PRECISION	`DOUBLE` DOUBLE	Oracle/PostgreSQL
`INT16` INT16	`SMALLINT` SMALLINT	Spark
`INT32` INT32	`INT` INT	Spark
`INT64` INT64	`BIGINT` BIGINT	Spark
`FLOAT32` FLOAT32	`FLOAT` FLOAT	Spark
`FLOAT64` FLOAT64	`DOUBLE` DOUBLE	Spark

数据类型兼容性参考

数据类型映射

MySQL

PostgreSQL

Hive

Spark SQL

行为差异

类型转换失败的处理方式

CHAR 不补空格

VARCHAR/CHAR 超长静默截断

INSERT VALUES 中字符串不隐式转为日期类型

NOT IN 包含 NULL

Spark SQL 兼容性说明

不支持的别名

相关文档