Enforce exact length on inserts into Apache Iceberg™ fixed[L] columns (Pending)

注意

此行为变更包含在 2026_02 捆绑包中。

有关捆绑包的当前状态，请参阅 捆绑包历史记录。

Snowflake 将对向 Iceberg fixed[L] 列类型插入的数据强制执行精确长度要求。

变更前:

使用 Iceberg fixed[L] 数据类型的列接受不超过定义长度“L”（以字节为单位）的二进制值。允许短于 L 的值。

长度超过 L 的值会导致查询失败。

变更后:

Columns that use the Iceberg fixed[L] data type accept binary values that exactly match the defined length 'L' in bytes. INSERT statements that attempt to insert a binary value shorter than L result in the following error message: Binary value has length <len1>, but Iceberg fixed[<len2>] type requires exactly <len2> bytes for column '<column name>'.

此变更使 Snowflake 与 Iceberg 规范和其他与 Iceberg 兼容的引擎（如 Apache Spark™）保持一致。

以下列表总结了启用此变更后的行为：

  • 此变更适用于新的和现有的 Iceberg 表。

  • 此变更适用于 Snowflake 管理的 Iceberg 表和外部管理的 Iceberg 表。

  • 关于读取，此变更对较旧的快照或 Time Travel 没有影响。现有快照将保持可读，因为 Snowflake 仅验证 DML 操作期间的 Iceberg fixed[L] 数据类型的长度。

  • 关于写入操作，启用此变更后，Snowflake 将在写入 Iceberg fixed[L] 数据类型时始终强制执行正确的长度，包括在 Time Travel 期间。尝试插入与定义的长度“L”（以字节为单位）不完全匹配的二进制值的写入将始终失败。长于 L 的值仍会导致查询失败。

为避免服务中断，您需要采取以下措施：识别并解决受影响的列。

识别并解决受影响的列

本节介绍如何确定列是否受此 BCR 影响，并解决受影响的列。

第 1 步：确定受影响的列

要确定是否有任何受影响的列，请执行以下步骤：

  1. 运行 DESCRIBE ICEBERG TABLE 命令。

    在输出中，查找具有源 Iceberg 类型 fixed[L] 的列。如果您发现 Iceberg 类型 fixed[L] 的列，继续下一步。

  2. 运行以下查询：

    SELECT BOOLOR_AGG(OCTET_LENGTH(<column_name>) != L) from <table_name>

    如果查询返回 true，则该列包含长度不正确的值，因此该列会受到影响。

第 2 步：解决受影响的列

要解决受影响的列，请执行以下操作之一

允许在受影响的列中插入任意大小的二进制值，长度不超过最大长度

要解析受影响的列，您可以允许在受影响的列中插入任意大小的二进制值，长度不超过最大长度。

此解决方案可确保表的元数据和物理文件符合 Iceberg 规范，因此与外部引擎兼容。

要允许在受影响的列中插入任意大小的二进制值（不超过最大长度），请按照以下说明操作：

  • 如果您的表由 Spark 等外部引擎访问，则必须使用列类型 BINARY 重新创建表。

    要使用列类型 BINARY 重新创建表，请执行以下步骤：

    1. 要创建并填充基于包含受影响列的表的新表，请运行 CREATE ICEBERG TABLE ... AS SELECT（也称为 CTAS）命令，并将二进制指定为受影响列的数据类型。

      以下示例显示了 CTAS 语句，其中新表中 b 列的数据类型指定为二进制：

      CREATE ICEBERG TABLE my_table (..., b binary) AS SELECT * FROM my_old_table

    2. 使用 DROP ICEBERG TABLE 命令以移除包含受影响列的表。

  • 或者，您可以通过运行 ALTER ICEBERG TABLE 命令来演进表架构的模式，将该列的数据类型设置为 BINARY。

    重要

    在运行 ALTER ICEBERG TABLE 语句将列数据类型更改为 BINARY 之前，您必须首先联系 Snowflake 支持 为您的账户启用此功能。

    例如，以下语句通过将列 c 的数据类型更改为 BINARY，来演进表 t 的架构：

    ALTER ICEBERG TABLE t ALTER COLUMN c SET DATA TYPE BINARY;

    此方法是受支持的临时解决方案，适用于 BCR 期间受影响的客户。这种方法的优点是，您只需要更新表架构，而无需重新创建整个表。

    重要

    此方法不是有效的 Iceberg 类型提升，因此外部引擎可能会检测到无效的类型提升，并且无法刷新表。因此，这种方法只能用于 Snowflake 管理的 Iceberg 表，这些表不会被外部引擎读取或写入。

允许将长度恰好为 L 的固定长度二进制值插入到受影响的列中

要允许在受影响的列中插入长度正好为 L 的固定长度二进制值，请通过调整工作流程（例如使用修剪或填充）来确保输入值的大小与目标大小匹配。我们还建议您使用 Iceberg 列类型 fixed(L) 重新创建 Iceberg 表，以确保之前在表中插入的任何值的大小与定义的长度 L 完全匹配。

参考：2246