Apache Iceberg™ 表的数据类型¶

Snowflake 支持 Apache Iceberg™ 规范 (https://iceberg.apache.org/spec/) 定义的大部分数据类型，并会将 Iceberg 数据类型写入表文件，以便在您使用 Snowflake 作为目录时，Iceberg 表在不同的计算引擎之间保持互操作性。

有关 Snowflake 支持的 Iceberg 数据类型的概述，请参阅支持的数据类型。

近似类型¶

如果您的表使用的 Iceberg 数据类型不支持 精确匹配 ，Snowflake 会使用近似的 Snowflake 类型。此类型映射会影响使用 Snowflake 作为目录的转换表和 Iceberg 表的列值。

例如，考虑一个包含 Iceberg 类型 int 的列的表。Snowflake 使用 Snowflake 数据类型 NUMBER(10,0) 处理列值。

NUMBER(10,0) 的范围为 (-9,999,999,999, +9,999,999,999)，但 int 范围更有限，为 (-2,147,483,648, +2,147,483,647)。如果尝试在该列中插入值 3,000,000,000，则 Snowflake 将返回超出范围的错误消息。

有关近似类型的详细信息，请参阅支持的数据类型表中的备注。

支持的数据类型¶

本节中的表显示了 Iceberg 数据类型和 Snowflake 数据类型之间的关系。它们使用以下列：

Iceberg 类型:: Apache Iceberg 规范中定义的数据类型。使用 Snowflake 作为目录时，Snowflake 会将 Iceberg 类型写入表数据文件，以便表在不同的计算引擎之间保持互操作性。
Snowflake 类型:: 用于处理和返回表数据的 Snowflake 数据类型。例如，如果架构指定了 Iceberg 类型 timestamp，则 Snowflake 将使用 Snowflake 数据类型 TIMESTAMP_NTZ(6) 以微秒精度处理并返回值。
备注:: 其他使用说明，包括有关使用近似类型的说明。

数值类型¶

使用 Snowflake 作为目录¶

下表显示了对于使用 Snowflake 作为 Iceberg 目录的表（由 Snowflake 管理的表），Iceberg 数值数据类型如何映射到 Snowflake 数值数据类型。当您创建 Snowflake 管理的 Iceberg 表时，可使用 Iceberg 数据类型 (https://iceberg.apache.org/spec/#schemas-and-data-types) 来定义数值列。

Iceberg 数据类型	Snowflake 数据类型	备注
:code:`int`（32 位带符号整数）	NUMBER(10,0)	如果插入的 10 位数小于最小值，或大于最大的 32 位带符号整数值，则会导致超出范围错误。
:code:`long`（64 位带符号整数）	NUMBER (19,0)	如果插入的 19 位数小于最小值，或大于最大的 64 位带符号整数值，则会导致超出范围错误。
:code:`float`（单精度 32 位 IEEE 754 浮点）	FLOAT	与 Snowflake DOUBLE 数据类型同义。Snowflake 将所有浮点数都视为双精度 64 位浮点数，但会将 Iceberg 浮点数作为 32 位浮点数写入表数据文件。将转换从 64 位缩窄到 32 位会导致精度损失。您不能使用 `float` 或 `double` 作为主键（根据 Apache Iceberg 规范 (https://iceberg.apache.org/spec/#identifier-field-ids)）。
:code:`double`（双精度 64 位 IEEE 754 浮点）	FLOAT	与 Snowflake DOUBLE 数据类型同义。Snowflake 将所有浮点数都视为双精度 64 位浮点数。将转换从 64 位缩窄到 32 位会导致精度损失。您不能使用 `float` 或 `double` 作为主键（根据 Apache Iceberg 规范 (https://iceberg.apache.org/spec/#identifier-field-ids)）。
`decimal(P,S)`	NUMBER (P,S)	指定 `decimal(10,0)` 而不是 `int` 会在 Iceberg 中创建一个十进制类型。当您指定 `decimal(19,0)` 时也是如此。

外部目录¶

当您创建使用外部 Iceberg 目录的 Iceberg 表时，Iceberg 数值类型将根据下表映射到 Snowflake 数值类型。

Iceberg 数据类型	Snowflake 数据类型
:code:`int`（32 位带符号整数）	NUMBER(10,0)
:code:`long`（64 位带符号整数）	NUMBER (19,0)
:code:`float`（单精度 32 位 IEEE 754 浮点）	FLOAT
:code:`double`（双精度 64 位 IEEE 754 浮点）	FLOAT
`decimal(P,S)`	NUMBER (P,S)

备注

您不能使用 float 或 double 作为主键（根据 Apache Iceberg 规范 (https://iceberg.apache.org/spec/#identifier-field-ids)）。

其他数据类型¶

Iceberg 数据类型	Snowflake 数据类型	备注
`boolean`	BOOLEAN
`date`	DATE
`time`	TIME (6)	基于 Apache Iceberg 表规范的微秒级精度。
`timestamp`	TIMESTAMP_NTZ (6) 或 TIMESTAMP_LTZ (6)，这取决于 Snowflake 参数 TIMESTAMP_TYPE_MAPPING 的值。	基于 Apache Iceberg 表规范的微秒级精度。您还可以使用 Parquet 物理类型 `int96` 作为时间戳。Snowflake 将 `timestamp` 转换为微秒（根据 Apache Iceberg 表规范）。
`timestamptz`	TIMESTAMP_LTZ (6)	基于 Apache Iceberg 表规范的微秒级精度。您还可以使用 Parquet 物理类型 `int96` 作为时间戳。Snowflake 将 `timestamp` 转换为微秒（根据 Apache Iceberg 表规范）。
`string`	VARCHAR (16777216)
`uuid`	BINARY (16)	使用 Snowflake 作为目录的表或转换后的表不支持 `uuid` 数据类型。使用外部目录或从对象存储中的文件创建表时，Snowflake 会将 `uuid` Iceberg 类型映射到 BINARY (16) Snowflake 类型。
`struct`	结构化 OBJECT	结构化类型列最多支持 1000 个子列。
`list`	结构化 ARRAY	结构化类型列最多支持 1000 个子列。
`map`	MAP	结构化类型列最多支持 1000 个子列。

Delta 数据类型¶

下表显示了对于从Delta 表文件创建的 Iceberg 表，如何将 Delta 数据类型映射到 Snowflake 数据类型。

Delta 类型	Snowflake 数据类型
BYTE	NUMBER (3,0)
SHORT	NUMBER (5,0)
INTEGER	NUMBER (10,0)
LONG	NUMBER (20,0)
FLOAT	REAL
DOUBLE	REAL
TIMESTAMP	TIMESTAMP_LTZ (6)
TIMESTAMP_NTZ	TIMESTAMP_NTZ (6)
BINARY	BINARY
STRING	TEXT
BOOLEAN	BOOLEAN
DECIMAL (P,S)	NUMBER (P,S)

下表显示了 Delta 嵌套数据类型如何映射到 Snowflake 数据类型。

Delta 嵌套类型	Snowflake 数据类型
STRUCT	结构化 OBJECT
ARRAY	结构化 ARRAY
MAP	MAP

注意事项¶

使用 Iceberg 表的数据类型时，请注意以下事项：

不支持转换其列使用以下 Iceberg 数据类型的表：
- uuid
- fixed(L)
对于使用 Snowflake 作为目录的表，不支持创建使用 Iceberg uuid 数据类型的表。
适用于所有 Iceberg 表类型：
- 结构化类型列最多支持 1000 个子列。
- 对于时间和时间戳类型，Iceberg 支持微秒精度。因此，您无法在 Snowflake 中创建使用其他精度（如毫秒或纳秒）的 Iceberg 表。
- 您不能使用 float 或 double 作为主键（根据 Apache Iceberg 规范 (https://iceberg.apache.org/spec/#identifier-field-ids)）。
对于从 Delta 文件创建的表：
- 不支持使用以下任何功能或数据类型的 Parquet 文件（Delta 表的数据文件）：
  - 字段 IDs。
  - INTERVAL 数据类型。
  - 精度高于 38 的 DECIMAL 数据类型。
  - LIST 或 MAP 类型的一级或两级表示。
  - 无符号整型 (INT(signed = false))。
  - FLOAT16 数据类型。