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

工作流程¶

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

1. Configure a catalog integration with vended credentials. For instructions, see 为 Apache Iceberg™ 表使用由目录分发的凭据.

   备注

   If your remote Iceberg catalog doesn't support credential vending, you must configure an external volume and a catalog integration.

   First, configure an external volume for your cloud storage provider. Ensure that both read and write operations are allowed for the external volume by setting the ALLOW_WRITES parameter to TRUE, which is the default. For more information about the required permissions, see 授予 Snowflake 对存储的访问权限.

   Then, configure a Apache Iceberg™ REST catalog integration for your remote Iceberg catalog. Your remote catalog must comply with the open source Apache Iceberg REST OpenAPI specification (https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml), If you currently use a catalog integration for AWS Glue, you must create a new REST catalog integration for the AWS Glue Iceberg REST endpoint.

2. 从以下选项中选择：

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

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

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

创建目录链接数据库¶

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

The following example uses the CREATE DATABASE（目录链接） command to create a catalog-linked database that uses catalog-vended credentials:

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  );

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'
  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}''

注意事项¶

对外部托管的 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 表时，以下功能暂不支持：

  • Server-side encryption (SSE) for Azure external volumes.

  • 多语句事务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.

• Sharing:

  • Sharing with a listing isn't currently supported.

  • Direct sharing isn’t currently supported.