对外部托管的 Apache Iceberg™ 表的写入支持¶

注意事项¶

对外部托管的 Iceberg 表使用写入支持时，请考虑以下事项：

• Snowflake supports externally managed writes for Iceberg tables that use version 2 of the Iceberg table specification (https://iceberg.apache.org/spec/).

• Snowflake 为外部托管的表提供数据定义语言 (DDL) 和数据操作语言 (DML) 命令。但是，您可以使用外部目录和外部存储提供商提供的工具来配置元数据和数据保留。有关更多信息，请参阅 使用外部目录的表。

  对于写入，Snowflake 确保在更新 Snowflake 中的表之前将更改提交到您的远程目录。

• 如果您使用目录链接的数据库，则可以使用带列定义的 CREATE ICEBERG TABLE 语法在 Snowflake 和 远程目录中创建表。如果您使用标准的 Snowflake 数据库（未链接到目录），则必须先在远程目录中创建表。之后，您可以使用 CREATE ICEBERG TABLE（Iceberg REST 目录） 语法在 Snowflake 中创建一个 Iceberg 表并将数据写入该表。

• For the AWS Glue Data Catalog: Dropping an externally managed table through Snowflake doesn't delete the underlying table files. This behavior is specific to the AWS Glue Data Catalog implementation.

• Position row-level deletes (https://iceberg.apache.org/spec/#row-level-deletes) are supported for tables stored on Amazon S3, Azure, or Google Cloud. Row-level deletes with equality delete files aren't supported. For more information about row-level deletes, see 使用行级删除. To turn off position deletes, which enable running the DML operations in copy-on-write mode, set the ENABLE_ICEBERG_MERGE_ON_READ parameter to FALSE at the table, schema, or database level.

• 不支持对包含以下 Iceberg 数据类型的外部托管表进行写入操作：

  • uuid

  • fixed(L)

• 在使用 Snowflake 写入外部托管的 Iceberg 表时，以下功能暂不支持：

  • 目录分发的凭据。

  • GCS 或 Azure 外部卷的服务器端加密 (SSE)。

  • 多语句事务Snowflake 仅支持自动提交事务。

  • 转换为 Snowflake 托管的表。

  • 不符合 Iceberg REST 协议的外部 Iceberg 目录。

  • 行级删除（读取时合并）。

  • 创建表时使用 OR REPLACE 选项。

  • 如果使用 AWS Glue 作为远程目录，应使用 CREATE TABLE ... AS SELECT 语法。

• 要在目录链接数据库中创建架构，请注意以下事项：

  • 仅当您使用目录链接的数据库时，CREATE SCHEMA 命令才会在远程目录中创建相应的命名空间。

  • 不支持 ALTER 和 CLONE 选项。

  • 架构名称不支持分隔符。仅支持字母数字架构名称。

• You can set a target file size for a table's Parquet files. For more information, see Set a target file size.

• For Azure cloud storage services: Snowflake only supports externally managed writes for Iceberg tables that use the following services for external storage:

  • Blob storage

  • Data Lake Storage Gen2

  • General-purpose v1

  • General-purpose v2

  • Microsoft Fabric OneLake

  These services use blob endpoints. Services that use distributed file system (DFS) endpoints, including Azure Data Lake Storage Gen2 (ADLS), aren't supported. When you create your external Iceberg REST catalog, make sure you use a service for external storage that supports blob endpoints.

工作流程¶

使用本不分中的工作流程开始使用此功能：

1. 配置外部卷

2. 创建目录集成

3. 从以下选项中选择：

   • 创建目录链接数据库。通过此选项，您可以向目录中自动发现的 Iceberg 表写入数据，或使用目录链接的数据库创建更多 Iceberg 表。

   • :ref:`创建 Iceberg 表 <label-tables_iceberg_external_writes_create_table>`（在目录链接数据库或标准 Snowflake 数据库中）。使用此选项，必须先在远程目录中创建表，然后才能在 Snowflake 中创建外部托管的 Iceberg 表。

完成这些步骤后，您可以对 Iceberg 表执行 写入操作。

配置外部卷以写入到外部托管的表¶

要启用对外部托管表的写入功能，必须使用为 Snowflake 服务主体配置了读写权限的外部卷（该权限要求与 Snowflake 托管表所需的权限相同）。

请指定您的 Iceberg REST 目录用于写入 Iceberg 数据和元数据的存储位置 (STORAGE_BASE_URL)。

例如，以下语句可为 S3 创建一个启用加密的外部卷，该卷允许对名为 my-iceberg-tables 的存储桶进行写入访问：

CREATE OR REPLACE EXTERNAL VOLUME my_external_volume
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-s3-us-west-2'
        STORAGE_PROVIDER = 'S3'
        STORAGE_BASE_URL = 's3://my-iceberg-tables/'
        STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-write-access-role'
        ENCRYPTION = ( TYPE = 'AWS_SSE_S3' )
      )
    )
  ALLOW_WRITES = TRUE;

有关完整说明，请参阅以下主题：

• 为 Amazon S3 配置外部卷

• 为 Google Cloud Storage 配置外部卷

• 为 Azure 存储配置外部卷

有关所需权限的更多信息，请参阅 授予 Snowflake 对存储的访问权限。

配置目录集成¶

要写入外部托管的 Iceberg 表，必须配置目录集成以将 Snowflake 连接到远程目录。

您的远程目录必须符合开源 Apache Iceberg REST OpenAPI 规范 (https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)，例如 Open Catalog 或 AWS Glue Iceberg REST 目录 (https://docs.aws.amazon.com/glue/latest/dg/connect-glu-iceberg-rest.html)。

要创建目录集成，请参阅以下主题中的说明：

• 为 AWS Glue Iceberg REST 配置目录集成。使用 读取和写入示例 IAM 策略 中的权限。

  备注

  如果您当前使用 AWS Glue 的目录集成，则必须为 AWS Glue Iceberg REST 端点创建新的 REST 目录集成。

• 为 Snowflake Open Catalog 配置目录集成

• 为 Apache Iceberg™ REST 目录配置目录集成

创建目录链接数据库¶

Snowflake 支持在目录链接数据库中创建可写的外部托管表，该数据库是与外部 Iceberg REST 目录同步的 Snowflake 数据库。您也可以向 Snowflake 在远程目录中自动发现的 Iceberg 表写入数据。有关更多信息，请参阅 为 Apache Iceberg™ 表使用目录链接的数据库。

以下示例使用 CREATE DATABASE（目录链接） 命令创建使用外部卷的目录链接数据库：

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  ),
  EXTERNAL_VOLUME = 'my_external_vol';

CREATE SCHEMA 'my_namespace';

DROP SCHEMA 'my_namespace';

创建 Iceberg 表¶

创建可从 Snowflake 写入的外部托管 Iceberg 表的具体操作会因您使用的数据库类型而异：

• 如果您使用目录链接的数据库，则可以使用 CREATE ICEBERG TABLE（目录链接的数据库） 创建表 并 将其注册到远程目录中。有关说明，请参阅 在目录链接的数据库中创建 Iceberg 表。

• 如果您使用标准的 Snowflake 数据库（未链接到目录），则必须先在远程目录中创建表。之后，您可以使用 CREATE ICEBERG TABLE（Iceberg REST 目录） 语法在 Snowflake 中创建一个 Iceberg 表并将数据写入该表。有关说明，请参阅 在标准 Snowflake 数据库中创建 Iceberg 表。

USE DATABASE my_catalog_linked_db;

USE SCHEMA my_namespace;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name STRING,
  last_name STRING,
  amount INT,
  create_date DATE
)
TARGET_FILE_SIZE = '64MB'
PARTITION BY (first_name);

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table_name';

删除 Iceberg 表¶

您可以使用 DROP ICEBERG TABLE 命令同时从 Snowflake 和远程目录中删除外部托管的可写入的 Iceberg 表。

DROP ICEBERG TABLE my_iceberg_table;

Snowflake 会删除该表，同时调用您的远程 Iceberg 目录，指示其删除该表并清除表的底层数据和元数据。

只有在确认表已成功从远程目录中删除后，Snowflake 才会删除该表。

写入外部托管的 Iceberg 表¶

您可以对外部托管的 Iceberg 表使用以下 DML 命令：

• INSERT

  • 示例：使用查询进行单行插入 (INSERT INTO ... SELECT FROM)

  • 示例：INSERT INTO ... SELECT FROM（流）

• UPDATE

• DELETE

• MERGE

• TRUNCATE TABLE

• COPY INTO <table>。有关更多信息，请参阅 将数据加载到 Apache Iceberg™ 表中。

您也可以使用 Snowpark API 来处理 Iceberg 表。

INSERT INTO my_iceberg_table VALUES (1, 'a');
INSERT INTO my_iceberg_table VALUES (2, 'b');
INSERT INTO my_iceberg_table VALUES (3, 'c');

UPDATE my_iceberg_table
  SET a = 10
  WHERE b = 'b';

DELETE my_iceberg_table
  WHERE b = 'a';

MERGE INTO my_iceberg_table USING my_snowflake_table
  ON my_iceberg_table.a = my_snowflake_table.a
  WHEN MATCHED THEN
      UPDATE SET my_iceberg_table.b = my_snowflake_table.b
  WHEN NOT MATCHED THEN
      INSERT VALUES (my_snowflake_table.a, my_snowflake_table.b);

COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;

//...

INSERT INTO my_iceberg_table(id,name)
  SELECT id, name
  FROM my_stream;

def copy_into_iceberg():

  try:
      df = session.table("my_snowflake_table")

      df.write.save_as_table("my_iceberg_table")

  except Exception as e:
      print(f"Error processing {table_name}: {e}")

故障排除¶

如果 Snowflake 尝试向外部目录提交表更改时出现问题，Snowflake 会返回以下错误消息之一。

004185=SQL Execution Error: Failed while committing transaction to external catalog. Error:''{0}''

004185=SQL Execution Error: Failed while committing transaction to external catalog with unresolvable commit conflicts. Error:''{0}''

004500=SQL Execution Error: Cannot verify the status of transaction from external catalog. The statement ''{0}'' with transaction id {1} may or may not have committed to external catalog. Error:''{2}''