Apache Iceberg™ tables¶Apache Iceberg™ 表

Apache Iceberg™ tables for Snowflake combine the performance and query semantics of typical Snowflake tables with external cloud storage that you manage. They are ideal for existing data lakes that you cannot, or choose not to, store in Snowflake.Snowflake 的 Apache Iceberg™ 表结合了典型 Snowflake 表的性能和查询语义，以及由您管理的外部云存储。它们非常适合您无法或选择不存储在 Snowflake 中的现有数据湖。

Iceberg tables use the Apache Iceberg™ open table format specification, which provides an abstraction layer on data files stored in open formats and supports features such as:Iceberg 表使用 Apache Iceberg™ 开放表格式规范，该规范为存储在开放格式中的数据文件提供了一个抽象层，并支持以下功能：

• ACID (atomicity, consistency, isolation, durability) transactionsACID（原子性、一致性、隔离性、持久性）事务
• Schema evolution模式演进
• Hidden partitioning隐藏分区
• Table snapshots表快照

Snowflake supports Iceberg tables that use the Apache Parquet™ file format.Snowflake 支持使用 Apache Parquet™ 文件格式的 Iceberg 表。

Getting started¶入门指南

To get started with Iceberg tables, see Tutorial: Create your first Apache Iceberg™ table.要开始使用 Iceberg 表，请参阅教程：创建您的第一个 Apache Iceberg™ 表。

How it works¶工作原理

This section provides information specific to working with Iceberg tables in Snowflake. To learn more about the Iceberg table format specification, see the official Apache Iceberg documentation and the Iceberg Table Spec.本节提供有关在 Snowflake 中使用 Iceberg 表的具体信息。要详细了解 Iceberg 表格式规范，请参阅 Apache Iceberg 官方文档和 Iceberg 表规范。

• Data storage数据存储
• Catalog目录
• Metadata and snapshots元数据和快照
• Cross-cloud/cross-region support跨云/跨区域支持
• Billing计费

Data storage¶数据存储

Iceberg tables store their data and metadata files in cloud storage. You choose one of two storage options:Iceberg 表将其数据和元数据文件存储在云存储中。您可以选择以下两种存储选项之一：

• Snowflake storage (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED): Snowflake stores and manages the files for you. Permanent tables are protected by Fail-safe. Snowflake bills you for this storage.Snowflake 存储 (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED)：Snowflake 为您存储和管理这些文件。永久表受故障保护 (Fail-safe) 机制保护。Snowflake 会针对此存储向您收费。
• External volume storage: The files are in an external cloud storage location that you manage (Amazon S3, Google Cloud Storage, or Azure Storage). You’re responsible for data protection and recovery. Snowflake doesn’t provide Fail-safe for these tables, and your cloud provider bills you for storage.外部卷存储：文件位于您管理的外部云存储位置（Amazon S3、Google Cloud Storage 或 Azure Storage）。您负责数据保护和恢复。Snowflake 不为这些表提供故障保护，并且您的云提供商会向您收取存储费用。

Snowflake connects to customer-managed storage using an external volume.Snowflake 使用外部卷连接到客户管理的存储。

To compare the options, see Storage for Apache Iceberg™ tables. For billing details, see Billing.要比较这些选项，请参阅 Apache Iceberg™ 表的存储。有关计费详情，请参阅计费。

External volume¶外部卷

To set up an external volume for Iceberg tables, see Configure an external volume.要设置 Iceberg 表的外部卷，请参阅配置外部卷。

Catalog¶目录

An Iceberg catalog enables a compute engine to manage and load Iceberg tables. The catalog forms the first architectural layer in the Iceberg table specification and must support:Iceberg 目录使计算引擎能够管理和加载 Iceberg 表。目录构成了 Iceberg 表规范中的第一层架构，并且必须支持：

• Storing the current metadata pointer for one or more Iceberg tables. A metadata pointer maps a table name to the location of that table’s current metadata file.存储一个或多个 Iceberg 表的当前元数据指针。元数据指针将表名映射到该表当前元数据文件的位置。
• Performing atomic operations so that you can update the current metadata pointer for a table.执行原子操作，以便您可以更新表的当前元数据指针。

To learn more about Iceberg catalogs, see the Apache Iceberg documentation.要详细了解 Iceberg 目录，请参阅 Apache Iceberg 文档。

Snowflake supports different catalog options. For example, you can use Snowflake as the Iceberg catalog, or use a catalog integration to connect Snowflake to an external Iceberg catalog.Snowflake 支持不同的目录选项。例如，您可以将 Snowflake 用作 Iceberg 目录，或者使用目录集成将 Snowflake 连接到外部 Iceberg 目录。

Catalog integration¶目录集成

To set up a catalog integration, see Configure a catalog integration.要设置目录集成，请参阅配置目录集成。

Metadata and snapshots¶元数据和快照

Iceberg uses a snapshot-based querying model, where data files are mapped using manifest and metadata files. A snapshot represents the state of a table at a point in time and is used to access the complete set of data files in the table.Iceberg 使用基于快照的查询模型，其中数据文件通过清单文件和元数据文件进行映射。快照代表表在特定时间点的状态，用于访问表中完整的数据文件集。

To learn about table metadata and Time Travel support, see Metadata and retention for Apache Iceberg™ tables.要了解表元数据和时间旅行 (Time Travel) 支持，请参阅 Apache Iceberg™ 表的元数据和保留策略。

Cross-cloud/cross-region support¶跨云/跨区域支持

Snowflake supports using an external volume storage location with a different cloud provider (in a different region) from the one that hosts your Snowflake account.Snowflake 支持使用与托管 Snowflake 账户的云提供商（在不同区域）不同的云提供商（在不同区域）的外部卷存储位置。

Billing¶计费

Snowflake bills your account for virtual warehouse (compute) usage and cloud services when you work with Iceberg tables. Snowflake also bills your account if you use automated refresh or an external query engine through Snowflake Horizon Catalog.当您使用 Iceberg 表时，Snowflake 会针对虚拟仓库（计算）使用量和云服务向您的账户收费。如果您使用自动刷新或通过 Snowflake Horizon Catalog 使用外部查询引擎，Snowflake 也会向您的账户收费。

For Snowflake-managed Iceberg tables, Snowflake bills cross-cloud and cross-region data transfer that Snowflake meters under the DATA_LAKE value of the TRANSFER_TYPE column in the DATA_TRANSFER_HISTORY views. To learn more, see:对于 Snowflake 管理的 Iceberg 表，Snowflake 会对跨云和跨区域的数据传输进行计费，Snowflake 在 DATA_TRANSFER_HISTORY 视图的 TRANSFER_TYPE 列中将其记录为 DATA_LAKE 值。要了解更多信息，请参阅：

• DATA_TRANSFER_HISTORY view in the ORGANIZATION_USAGE schema.ORGANIZATION_USAGE 模式中的 DATA_TRANSFER_HISTORY 视图。
• DATA_TRANSFER_HISTORY view in the ACCOUNT_USAGE schema.ACCOUNT_USAGE 模式中的 DATA_TRANSFER_HISTORY 视图。

Cross-cloud and cross-region billing depends on where the table stores data and how the table is accessed:跨云和跨区域计费取决于表存储数据的位置以及表的访问方式：

• For Snowflake-managed Iceberg tables on Snowflake storage (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED), Snowflake bills all cross-cloud and cross-region egress. This includes when an external query engine through Snowflake Horizon Catalog reads the table from a different region or cloud platform. For more information, see Data transfer cost.对于 Snowflake 存储上的 Snowflake 管理的 Iceberg 表 (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED)，Snowflake 对所有跨云和跨区域的出站流量收费。这包括通过 Snowflake Horizon Catalog 的外部查询引擎从不同区域或云平台读取表的情况。有关更多信息，请参阅数据传输成本。
• For Snowflake-managed Iceberg tables on customer-managed storage (an external volume that you manage):
  • Snowflake writes in a cross-cloud or cross-region configuration result in Snowflake egress charges under DATA_LAKE. This includes tables that use S3-compatible storage, which Snowflake treats as cross-cloud access.在跨云或跨区域配置中进行的 Snowflake 写入操作会导致 DATA_LAKE 下的 Snowflake 出站费用。这包括使用 S3 兼容存储的表，Snowflake 将其视为跨云访问。
  • Reads and writes by an external query engine through Snowflake Horizon Catalog: Your cloud storage provider bills you for egress when data files move across regions or cloud platforms.通过 Snowflake Horizon Catalog 进行的外部查询引擎的读取和写入操作：当数据文件跨区域或云平台移动时，您的云存储提供商会向您收取出站费用。

Snowflake does not bill your account for the following:Snowflake 不会针对以下情况向您的账户收费：

• Iceberg table storage costs when the table uses an external volume that you manage. Your cloud storage provider bills you directly for data storage usage. However, if the table uses Snowflake Storage (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED), Snowflake charges for the storage. For more information, see Snowflake storage for Apache Iceberg™ tables.当表使用您管理的外部卷时的 Iceberg 表存储成本。您的云存储提供商会直接向您收取数据存储使用费。但是，如果表使用 Snowflake 存储 (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED)，则 Snowflake 会收取存储费用。有关更多信息，请参阅 Apache Iceberg™ 表的 Snowflake 存储。
• Active bytes used by Iceberg tables. However, the INFORMATION_SCHEMA.TABLE_STORAGE_METRICS and ACCOUNT_USAGE.TABLE_STORAGE_METRICS views display ACTIVE_BYTES for Iceberg tables to help you track how much storage a table occupies. To view an example, see Retrieve storage metrics.Iceberg 表使用的活动字节数 (Active bytes)。但是，INFORMATION_SCHEMA.TABLE_STORAGE_METRICS 和 ACCOUNT_USAGE.TABLE_STORAGE_METRICS 视图会显示 Iceberg 表的 ACTIVE_BYTES，以帮助您跟踪表占用的存储量。要查看示例，请参阅检索存储指标。

Catalog options¶目录选项

Snowflake supports the following Iceberg catalog options:Snowflake 支持以下 Iceberg 目录选项：

• Use Snowflake as the Iceberg catalog将 Snowflake 用作 Iceberg 目录
• Use an external Iceberg catalog使用外部 Iceberg 目录

The following table summarizes the differences between these catalog options.下表总结了这些目录选项之间的区别。

Use Snowflake as the catalog¶将 Snowflake 用作目录

An Iceberg table that uses Snowflake as the Iceberg catalog (Snowflake-managed Iceberg table) provides full Snowflake platform support with read and write access. You can choose where the table data and metadata files are stored:使用 Snowflake 作为 Iceberg 目录的 Iceberg 表（Snowflake 管理的 Iceberg 表）提供完整的 Snowflake 平台支持，包括读写访问权限。您可以选择表数据和元数据文件的存储位置：

• Snowflake storage: Snowflake stores and manages the Iceberg table files for you, so you don’t need to configure or grant access to external cloud storage.Snowflake 存储：Snowflake 为您存储和管理 Iceberg 表文件，因此您无需配置或授予对外部云存储的访问权限。
• External cloud storage that you manage, which Snowflake accesses using an external volume.您管理的外部云存储，Snowflake 通过外部卷访问该存储。

Snowflake handles all lifecycle maintenance, such as compaction, for the table. However, you can disable compaction for the table, if needed.Snowflake 处理表的生命周期维护，例如压缩。但是，如果需要，您可以禁用表的压缩。

Use an external catalog¶使用外部目录

An Iceberg table that uses an external catalog provides limited Snowflake platform support.使用外部目录的 Iceberg 表提供有限的 Snowflake 平台支持。

With this table type, Snowflake uses a catalog integration to retrieve information about your Iceberg metadata and schema.对于这种表类型，Snowflake 使用目录集成来检索有关您的 Iceberg 元数据和模式的信息。

You can use this option to create an Iceberg table for the following sources:您可以使用此选项为以下来源创建 Iceberg 表：

• Remote Iceberg REST catalog, including AWS Glue and Snowflake Open Catalog. Snowflake supports writes to externally managed tables that use a remote Iceberg REST catalog.远程 Iceberg REST 目录，包括 AWS Glue 和 Snowflake Open Catalog。Snowflake 支持向使用远程 Iceberg REST 目录的外部管理表进行写入。

  Tip提示

  To bring your external data from a remote Iceberg REST catalog into Snowflake, you can create a catalog-linked database. The database automatically discovers and stays in sync with the namespaces and tables in your remote catalog. You can use a catalog-linked database to read and write to the tables in your remote catalog from Snowflake, while preserving full interoperability with your existing Iceberg ecosystem. For more information, see the following topics:要将远程 Iceberg REST 目录中的外部数据引入 Snowflake，您可以创建目录链接数据库。该数据库会自动发现并与远程目录中的命名空间和表保持同步。您可以使用目录链接数据库从 Snowflake 读取和写入远程目录中的表，同时保持与现有 Iceberg 生态系统的完全互操作性。有关更多信息，请参阅以下主题：

  • Use a catalog-linked database for Apache Iceberg™ tables为 Apache Iceberg™ 表使用目录链接数据库
  • If your external data is in Unity Catalog, see Tutorial: Set up bidirectional access to Apache Iceberg™ tables in Databricks Unity Catalog如果您的外部数据位于 Unity Catalog 中，请参阅教程：在 Databricks Unity Catalog 中设置对 Apache Iceberg™ 表的双向访问
  • If your external data is in AWS Glue, see Build Data Lakes using Apache Iceberg with Snowflake and AWS Glue如果您的外部数据位于 AWS Glue 中，请参阅使用 Snowflake 和 AWS Glue 构建 Apache Iceberg 数据湖

• Delta table files in object storage (Delta Direct; see CREATE ICEBERG TABLE (Delta files in object storage))对象存储中的 Delta 表文件（Delta Direct；请参阅 CREATE ICEBERG TABLE (对象存储中的 Delta 文件)）

• Iceberg metadata files in object storage对象存储中的 Iceberg 元数据文件

Snowflake does not assume any life-cycle management on the table.Snowflake 不会对该表承担任何生命周期管理。

The table data and metadata are stored in external cloud storage, which Snowflake accesses using an external volume.表数据和元数据存储在外部云存储中，Snowflake 通过外部卷访问该存储。

The following diagram shows how an Iceberg table uses a catalog integration with an external Iceberg catalog.下图显示了 Iceberg 表如何使用带有外部 Iceberg 目录的目录集成。

Considerations and limitations¶注意事项和限制

The following considerations and limitations apply to Iceberg tables, and are subject to change:以下注意事项和限制适用于 Iceberg 表，且可能随时更改：

Clouds and regions云和区域

• Iceberg tables are available for all Snowflake accounts, on all cloud platforms and in all regions.Iceberg 表适用于所有 Snowflake 账户、所有云平台和所有区域。
• Cross-cloud/cross-region tables are supported. For more information, see Cross-cloud/cross-region support.支持跨云/跨区域表。有关更多信息，请参阅跨云/跨区域支持。

IcebergIceberg

• Versions 1, 2, and 3 of the Apache Iceberg specification are supported, excluding the following features:支持 Apache Iceberg 规范的第 1、2 和 3 版，但不包括以下功能：

  • Row-level equality deletes. However, tables that use Snowflake as the catalog support Snowflake DELETE statements.行级等值删除。但是，使用 Snowflake 作为目录的表支持 Snowflake DELETE 语句。
  • Using the history.expire.min-snapshots-to-keep table property to specify the default minimum number of snapshots to keep. For more information, see Metadata and snapshots.使用 history.expire.min-snapshots-to-keep 表属性来指定默认保留的最小快照数。有关更多信息，请参阅元数据和快照。

• Iceberg partitioning with the bucket transform function impacts performance for queries that use conditional clauses to filter results.使用 bucket 转换函数的 Iceberg 分区会影响使用条件子句过滤结果的查询性能。

• For Iceberg tables that aren’t managed by Snowflake, be aware of the following:对于非 Snowflake 管理的 Iceberg 表，请注意以下事项：

  • Time travel to any snapshot generated after table creation is supported as long as you periodically refresh the table before the snapshot expires.只要您在快照过期前定期刷新表，就支持时间旅行 (Time Travel) 到表创建后生成的任何快照。

  • Converting a table that has an un-materialized identity partition column isn’t supported. An un-materialized identity partition column is created when a table defines an identity transform using a source column that doesn’t exist in a Parquet file.不支持转换具有未物化标识分区列的表。当表使用 Parquet 文件中不存在的源列定义标识转换时，会创建未物化的标识分区列。

  • For row-level deletes:对于行级删除：

    • Snowflake supports position deletes only for v2 Iceberg tables, and deletion vectors for v3 Iceberg tables.Snowflake 仅支持 v2 Iceberg 表的位置删除，以及 v3 Iceberg 表的删除向量。

    • Snowflake only supports position deletes with externally managed Iceberg tables.Snowflake 仅支持外部管理的 Iceberg 表的位置删除。

    • For the best read performance when you use row-level deletes, perform regular compaction and table maintenance to remove old delete files. For information, see Maintain tables that use an external catalog.为了在使用行级删除时获得最佳读取性能，请执行定期的压缩和表维护以删除旧的删除文件。有关信息，请参阅维护使用外部目录的表。

    • Excessive position deletes, especially dangling position deletes, might prevent table creation and refresh operations. To avoid this issue, perform table maintenance to remove extra position deletes.过多的位置删除，尤其是悬空的位置删除，可能会阻碍表创建和刷新操作。为避免此问题，请执行表维护以删除多余的位置删除。

      The table maintenance method to use depends on your external Iceberg engine. For example, you can use the rewrite_data_files method for Spark with the delete-file-threshold or rewrite-all options. For more information, see rewrite_data_files in the Apache Iceberg™ documentation.所使用的表维护方法取决于您的外部 Iceberg 引擎。例如，您可以将 rewrite_data_files 方法用于 Spark，并使用 delete-file-threshold 或 rewrite-all 选项。有关更多信息，请参阅 Apache Iceberg™ 文档中的 rewrite_data_files。

File formats文件格式

• Iceberg tables support Apache Parquet files.Iceberg 表支持 Apache Parquet 文件。
• Parquet files that use the unsigned integer logical type aren’t supported.不支持使用无符号整数逻辑类型的 Parquet 文件。

• For Parquet files that use the LIST logical type, be aware of the following:对于使用 LIST 逻辑类型的 Parquet 文件，请注意以下事项：

  • The three-level annotation structure with the element keyword is supported. For more information, see Parquet Logical Type Definitions. If your Parquet file uses an obsolete format with the array keyword, you must regenerate your data based on the supported format.支持带有 element 关键字的三级注释结构。有关更多信息，请参阅 Parquet 逻辑类型定义。如果您的 Parquet 文件使用带有 array 关键字的过时格式，则必须基于支持的格式重新生成数据。

External volumes外部卷

• You can’t access the cloud storage locations in external volumes using a storage integration.您不能使用存储集成来访问外部卷中的云存储位置。
• You must configure a separate trust relationship for each external volume that you create.您必须为您创建的每个外部卷配置单独的信任关系。
• You can use outbound private connectivity to access Snowflake-managed Iceberg tables and Iceberg tables that use a catalog integration for object storage, but cannot use it to access Iceberg tables that use other catalog integrations.您可以使用出站私有连接来访问 Snowflake 管理的 Iceberg 表以及使用目录集成进行对象存储的 Iceberg 表，但不能使用它来访问使用其他目录集成的 Iceberg 表。

• After you create a Snowflake-managed table, the path to its files in external storage does not change, even if you rename the table.在您创建 Snowflake 管理的表后，即使您重命名该表，其在外部存储中的文件路径也不会改变。

Metadata files元数据文件

• The metadata files don’t identify the most recent snapshot of an Iceberg table.元数据文件不会标识 Iceberg 表的最新快照。

• You can’t modify the location of the data files or snapshot using the ALTER ICEBERG TABLE command. To modify either of these settings, you must recreate the table (using the CREATE OR REPLACE ICEBERG TABLE syntax).您不能使用 ALTER ICEBERG TABLE 命令修改数据文件或快照的位置。要修改这些设置中的任何一个，必须重新创建表（使用 CREATE OR REPLACE ICEBERG TABLE 语法）。

• For tables that use an external catalog:对于使用外部目录的表：

  • Ensure that manifest files don’t contain duplicates. If duplicate files are present in the same snapshot, Snowflake returns an error that includes the path of the duplicate file.确保清单文件不包含重复项。如果同一快照中存在重复文件，Snowflake 会返回一条包含重复文件路径的错误。
  • You can’t create a table if the Parquet metadata contains invalid UTF-8 characters. Ensure that your Parquet metadata is UTF-8 compliant.如果 Parquet 元数据包含无效的 UTF-8 字符，则无法创建表。确保您的 Parquet 元数据符合 UTF-8 标准。

• Snowflake detects corruptions and inconsistencies in Parquet metadata produced outside of Snowflake, and surfaces issues through error messages.Snowflake 会检测在 Snowflake 之外生成的 Parquet 元数据中的损坏和不一致情况，并通过错误消息显示问题。

  It’s possible to create, refresh, or query externally managed (or converted) tables, even if the table metadata is inconsistent. When writing Iceberg data, ensure that the table’s metadata statistics (for example, RowCount or NullCount) match the data content.即使表元数据不一致，也可以创建、刷新或查询外部管理的（或转换后的）表。写入 Iceberg 数据时，请确保表的元数据统计信息（例如 RowCount 或 NullCount）与数据内容匹配。

• For tables that use Snowflake as the catalog, Snowflake processes DDL statements individually and produces metadata in a way that might differ from other catalogs. For more information, see DDL statements.对于使用 Snowflake 作为目录的表，Snowflake 会单独处理 DDL 语句，并以可能与其他目录不同的方式生成元数据。有关更多信息，请参阅 DDL 语句。

Clustering聚簇 (Clustering)

Clustering support depends on the type of Iceberg table.聚簇支持取决于 Iceberg 表的类型。

Table type	Notes
Tables that use Snowflake as the Iceberg catalog	Set a clustering key by using either the CREATE ICEBERG TABLE or the ALTER ICEBERG TABLE command. To set or manage a clustering key, see CREATE ICEBERG TABLE (Snowflake as the Iceberg catalog) and ALTER ICEBERG TABLE.
Tables that use an external catalog	Clustering is not supported.
Converted tables	Snowflake only clusters files if they were created after converting the table, or if the files have since been modified using a DML statement.

Expand

Show lessSee more

DeltaDelta

• Snowflake supports minReaderVersion 3 and can read all tables written by engines that use the latest version of Delta Lake, which is 4.0.0. Delta Lake version 4.0.0 includes support for deletion vectors and liquid clustering.Snowflake 支持 minReaderVersion 3，并且可以读取由使用最新版本 Delta Lake（即 4.0.0）的引擎编写的所有表。Delta Lake 4.0.0 版本包括对删除向量和流式聚簇 (liquid clustering) 的支持。
• Snowflake streams aren’t supported for Iceberg tables created from Delta table files with partition columns. However, insert-only streams for tables created from Delta files without partition columns are supported.Snowflake 流不支持从具有分区列的 Delta 表文件创建的 Iceberg 表。但是，支持从没有分区列的 Delta 文件创建的表的仅插入流。
• Iceberg tables created from Delta files that were created before the 2024_04 release bundle are not supported in dynamic tables.动态表不支持从 2024_04 版本包之前创建的 Delta 文件创建的 Iceberg 表。
• Snowflake doesn’t support creating Iceberg tables from Delta table definitions in the AWS Glue Data Catalog.Snowflake 不支持从 AWS Glue Data Catalog 中的 Delta 表定义创建 Iceberg 表。

• Parquet files (data files for Delta tables) that use any of the following features or data types aren’t supported:不支持使用以下任何功能或数据类型的 Parquet 文件（Delta 表的数据文件）：

  • Field IDs.字段 ID。
  • The INTERVAL data type.INTERVAL 数据类型。
  • The DECIMAL data type with precision higher than 38.精度高于 38 的 DECIMAL 数据类型。
  • LIST or MAP types with one-level or two-level representation.具有一级或二级表示的 LIST 或 MAP 类型。
  • Unsigned integer types (INT(signed = false)).无符号整数类型 (INT(signed = false))。
  • The FLOAT16 data type.FLOAT16 数据类型。

• You can use the Parquet physical type int96 for TIMESTAMP, but Snowflake doesn’t support int96 for TIMESTAMP_NTZ.您可以将 Parquet 物理类型 int96 用于 TIMESTAMP，但 Snowflake 不支持将 int96 用于 TIMESTAMP_NTZ。

• For more information about Delta data types and Iceberg tables, see Delta data types.有关 Delta 数据类型和 Iceberg 表的更多信息，请参阅 Delta 数据类型。
• For refresh behavior and examples, see Refresh.有关刷新行为和示例，请参阅刷新。
• The following Delta Lake features aren’t currently supported: Row Tracking, change data files, change metadata, DataChange, CDC, protocol evolution.目前不支持以下 Delta Lake 功能：行跟踪、变更数据文件、变更元数据、DataChange、CDC、协议演进。

Automated refresh自动刷新

• For catalog integrations created before Snowflake version 8.22 (or 9.2 for Delta-based tables), you must manually set the REFRESH_INTERVAL_SECONDS parameter before you enable automated refresh on tables that depend on that catalog integration. For instructions, see ALTER CATALOG INTEGRATION … SET AUTO_REFRESH.对于在 Snowflake 8.22 版本（或 Delta 表的 9.2 版本）之前创建的目录集成，您必须在启用依赖于该目录集成的表的自动刷新之前，手动设置 REFRESH_INTERVAL_SECONDS 参数。有关说明，请参阅 ALTER CATALOG INTEGRATION … SET AUTO_REFRESH。
• For catalog integrations for object storage, automated refresh is only supported for integrations with TABLE_FORMAT = DELTA.对于对象存储的目录集成，自动刷新仅支持 TABLE_FORMAT = DELTA 的集成。
• For tables with frequent updates, using a shorter polling interval (REFRESH_INTERVAL_SECONDS) can cause performance degradation.对于频繁更新的表，使用较短的轮询间隔 (REFRESH_INTERVAL_SECONDS) 可能会导致性能下降。
• Automated refresh synchronizes schema changes alongside DML operations such as INSERT, UPDATE, or DELETE. To apply schema changes made through DDL operations alone, perform a manual refresh.自动刷新会同步模式更改以及 DML 操作（如 INSERT、UPDATE 或 DELETE）。要仅应用通过 DDL 操作进行的模式更改，请执行手动刷新。

Catalog-linked databases and automatic table discovery目录链接数据库和自动表发现

• Supported only when you use a catalog integration for Iceberg REST (for example, Snowflake Open Catalog).仅当您使用 Iceberg REST 的目录集成（例如 Snowflake Open Catalog）时才支持。

• To limit automatic table discovery to a specific set of namespaces, use the ALLOWED_NAMESPACES parameter. You can also use the BLOCKED_NAMESPACES parameter to block a set of namespaces.要将自动表发现限制为特定的命名空间集，请使用 ALLOWED_NAMESPACES 参数。您还可以使用 BLOCKED_NAMESPACES 参数来阻止一组命名空间。

• Snowflake doesn’t sync remote catalog access control for users or roles.Snowflake 不会为用户或角色同步远程目录访问控制。

• You can create schemas, externally managed Iceberg tables, or database roles in a catalog-linked database. Creating other Snowflake objects isn’t currently supported.您可以在目录链接数据库中创建模式、外部管理的 Iceberg 表或数据库角色。目前不支持创建其他 Snowflake 对象。

• When you create a catalog-linked database, you can’t specify the default Iceberg version or merge-on-read behavior to use for Iceberg tables.创建目录链接数据库时，您无法指定用于 Iceberg 表的默认 Iceberg 版本或读时合并 (merge-on-read) 行为。

  However, you can modify these properties for an existing database by using the ALTER DATABASE (catalog-linked) command to set the following parameters:但是，您可以使用 ALTER DATABASE (目录链接) 命令设置以下参数来修改现有数据库的这些属性：

  • ICEBERG_VERSION_DEFAULTICEBERG_VERSION_DEFAULT
  • ICEBERG_MERGE_ON_READ_BEHAVIORICEBERG_MERGE_ON_READ_BEHAVIOR

• For Iceberg tables in a catalog-linked database:对于目录链接数据库中的 Iceberg 表：

  • Snowflake bidirectionally syncs table and column descriptions between the remote catalog and Snowflake. Sync can update a description to a new value, but never replaces a non-empty description with an empty one. Other remote catalog table properties, such as retention policies or buffers, aren’t copied, and altering table properties isn’t currently supported.Snowflake 在远程目录和 Snowflake 之间双向同步表和列描述。同步可以将描述更新为新值，但绝不会用空描述替换非空描述。远程目录的其他表属性（例如保留策略或缓冲区）不会被复制，并且目前不支持更改表属性。

  • Automated refresh is enabled by default. If the table-uuid of an external table and the catalog-linked database table don’t match, refresh fails and Snowflake drops the table from the catalog-linked database; Snowflake doesn’t change the remote table.自动刷新默认启用。如果外部表的 table-uuid 与目录链接数据库表不匹配，刷新将失败，Snowflake 会从目录链接数据库中删除该表；Snowflake 不会更改远程表。

  • If you drop a table from the remote catalog, Snowflake drops the table from the catalog-linked database. This action is asynchronous, so you might not see the change in the remote catalog right away.如果您从远程目录中删除表，Snowflake 会从目录链接数据库中删除该表。此操作是异步的，因此您可能不会立即在远程目录中看到更改。

  • If you rename a table in the remote catalog, Snowflake drops the existing table from the catalog-linked database and creates a table with the new name.如果您重命名远程目录中的表，Snowflake 会从目录链接数据库中删除现有表，并创建一个具有新名称的表。

  • Masking policies and tags are supported. Other Snowflake-specific features, including replication and cloning, aren’t supported.支持屏蔽策略和标签。不支持其他 Snowflake 特有功能，包括复制和克隆。

  • The character that you choose for the NAMESPACE_FLATTEN_DELIMITER parameter can’t appear in your remote namespaces. During the auto discovery process, Snowflake skips any namespace that contains the delimiter, and doesn’t create a corresponding schema in your catalog-linked database.您为 NAMESPACE_FLATTEN_DELIMITER 参数选择的字符不能出现在您的远程命名空间中。在自动发现过程中，Snowflake 会跳过任何包含该分隔符的命名空间，并且不会在您的目录链接数据库中创建相应的模式。

  • If you specify anything other than _, $, or numbers for the NAMESPACE_FLATTEN_DELIMITER parameter, you must put the schema name in quotes when you query the table.如果您为 NAMESPACE_FLATTEN_DELIMITER 参数指定了除 _、$ 或数字以外的任何内容，则在查询表时必须将模式名称放在引号中。

  • To check whether a namespace is nested under another namespace, use the SHOW SCHEMAS command and check the is_nested column in the output.要检查命名空间是否嵌套在另一个命名空间下，请使用 SHOW SCHEMAS 命令并检查输出中的 is_nested 列。

  • For databases linked to AWS Glue, you must use lowercase letters and surround the schema, table, and column names in double quotes. This is also required for other Iceberg REST catalogs that only support lowercase identifiers.对于链接到 AWS Glue 的数据库，您必须使用小写字母并将模式、表和列名称用双引号括起来。对于其他仅支持小写标识符的 Iceberg REST 目录，这也同样适用。

    The following example shows a valid query:以下示例显示了一个有效的查询：

    Copy code

    CREATE SCHEMA "s1";
    

    The following statements aren’t valid, because they use uppercase letters or omit the double quotes:以下语句无效，因为它们使用了大写字母或省略了双引号：

    Copy code

    CREATE SCHEMA s1;
    CREATE SCHEMA "Schema1";
    

  • Using UNDROP ICEBERG TABLE isn’t supported.不支持使用 UNDROP ICEBERG TABLE。

  • Sharing:共享：

    • Sharing with a listing is supported for catalog-linked databases that use Apache Iceberg™ REST catalog integrations.对于使用 Apache Iceberg™ REST 目录集成的目录链接数据库，支持通过列表进行共享。
    • Direct sharing is supported支持直接共享。

• For writing to tables in a catalog-linked database:对于写入目录链接数据库中的表：

  • Creating and writing to tables in nested namespaces is supported only when your catalog integration uses a catalog that supports nested namespaces. For other REST catalogs, creating and writing to tables in nested namespaces isn’t supported.仅当您的目录集成使用支持嵌套命名空间的目录时，才支持在嵌套命名空间中创建和写入表。对于其他 REST 目录，不支持在嵌套命名空间中创建和写入表。
  • Don’t use a period (.) in a namespace name unless period is the value you set for NAMESPACE_FLATTEN_DELIMITER and NAMESPACE_MODE is set to FLATTEN_NESTED_NAMESPACE. Otherwise, the namespace won’t be created.除非句点 (.) 是您为 NAMESPACE_FLATTEN_DELIMITER 设置的值且 NAMESPACE_MODE 设置为 FLATTEN_NESTED_NAMESPACE，否则请勿在命名空间名称中使用句点。否则，将不会创建该命名空间。
  • Position 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 Use row-level deletes. To turn off position deletes, which enable running the Data Manipulation Language (DML) operations in copy-on-write mode, set the ICEBERG_MERGE_ON_READ_BEHAVIOR parameter to 'DISABLED' at the table, schema, or database level.对于存储在 Amazon S3、Azure 或 Google Cloud 上的表，支持位置行级删除。不支持使用等值删除文件的行级删除。有关行级删除的更多信息，请参阅使用行级删除。要关闭位置删除（这允许在写时复制模式下运行数据操作语言 (DML) 操作），请在表、模式或数据库级别将 ICEBERG_MERGE_ON_READ_BEHAVIOR 参数设置为 'DISABLED'。

Externally managed write support外部管理写入支持

• Snowflake supports externally managed writes for Iceberg tables that use version 2 or version 3 of the Iceberg table specification.Snowflake 支持对使用 Iceberg 表规范第 2 版或第 3 版的 Iceberg 表进行外部管理写入。

• Snowflake provides Data Definition Language (DDL) and Data Manipulation Language (DML) commands for externally managed tables. However, you configure metadata and data retention using your external catalog and the tools provided by your external storage provider. For more information, see Tables that use an external catalog.Snowflake 为外部管理的表提供数据定义语言 (DDL) 和数据操作语言 (DML) 命令。但是，您可以使用外部目录和外部存储提供商提供的工具来配置元数据和数据保留。有关更多信息，请参阅使用外部目录的表。

  For writes, Snowflake ensures that changes are committed to your remote catalog before updating the table in Snowflake.对于写入操作，Snowflake 确保在更新 Snowflake 中的表之前将更改提交到您的远程目录。

• If you use a catalog-linked database, you can use the CREATE ICEBERG TABLE syntax with column definitions to create a table in Snowflake and in your remote catalog. If you use a standard Snowflake database (not linked to a catalog), you must first create a table in your remote catalog. After that, you can use the CREATE ICEBERG TABLE (Iceberg REST catalog) syntax to create an Iceberg table in Snowflake and write to it.如果您使用目录链接数据库，则可以使用带有列定义的 CREATE ICEBERG TABLE 语法在 Snowflake 和远程目录中创建表。如果您使用标准 Snowflake 数据库（未链接到目录），则必须首先在远程目录中创建表。之后，您可以使用 CREATE ICEBERG TABLE (Iceberg REST 目录) 语法在 Snowflake 中创建 Iceberg 表并对其进行写入。

• When you use CREATE OR REPLACE to create an Iceberg table, behavior depends on the database type:当您使用 CREATE OR REPLACE 创建 Iceberg 表时，行为取决于数据库类型：

  • Catalog-linked database: Snowflake drops and recreates the table in the remote catalog. The new table has a new table-uuid.目录链接数据库：Snowflake 删除并重新创建远程目录中的表。新表具有新的 table-uuid。
  • Standard Snowflake database (not linked to a catalog): Snowflake drops and recreates only the Snowflake table object. The table in the remote catalog is unchanged.标准 Snowflake 数据库（未链接到目录）：Snowflake 仅删除并重新创建 Snowflake 表对象。远程目录中的表保持不变。

• 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.对于 AWS Glue Data Catalog：通过 Snowflake 删除外部管理的表不会删除底层表文件。此行为是 AWS Glue Data Catalog 实现所特有的。

• Position 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 Use row-level deletes. To run DML operations in copy-on-write mode by disabling position deletes, set the ICEBERG_MERGE_ON_READ_BEHAVIOR parameter to 'DISABLED' at the table, schema, or database level.对于存储在 Amazon S3、Azure 或 Google Cloud 上的表，支持位置行级删除。不支持使用等值删除文件的行级删除。有关行级删除的更多信息，请参阅使用行级删除。要通过禁用位置删除在写时复制模式下运行 DML 操作，请在表、模式或数据库级别将 ICEBERG_MERGE_ON_READ_BEHAVIOR 参数设置为 'DISABLED'。

• The following features aren’t currently supported when you use Snowflake to write to externally managed Iceberg tables:当您使用 Snowflake 写入外部管理的 Iceberg 表时，目前不支持以下功能：

  • Server-side encryption (SSE) for Azure external volumes.Azure 外部卷的服务器端加密 (SSE)。

  • Multi-statement transactions. Snowflake supports autocommit transactions only.多语句事务。Snowflake 仅支持自动提交事务。

  • Conversion to Snowflake-managed tables.转换为 Snowflake 管理的表。

  • External Iceberg catalogs that don’t conform to the Iceberg REST protocol.不符合 Iceberg REST 协议的外部 Iceberg 目录。

  • Using the CREATE ICEBERG TABLE (catalog-linked database) … AS SELECT syntax if you use one of the following catalogs as your remote catalog:如果您使用以下目录之一作为远程目录，则无法使用 CREATE ICEBERG TABLE (目录链接数据库) … AS SELECT 语法：

    • AWS GlueAWS Glue
    • Databricks Unity CatalogDatabricks Unity Catalog

    Alternatively, you can use the CREATE ICEBERG TABLE (Iceberg REST catalog) syntax to create an empty Iceberg table and then use an INSERT INTO … SELECT statement to insert data into the empty table. However, this alternative uses two separate transactions, so it doesn’t guarantee atomicity.或者，您可以使用 CREATE ICEBERG TABLE (Iceberg REST 目录) 语法创建空的 Iceberg 表，然后使用 INSERT INTO … SELECT 语句将数据插入到空表中。但是，此替代方案使用两个单独的事务，因此不能保证原子性。

• For creating schemas in a catalog-linked database, be aware of the following:对于在目录链接数据库中创建模式，请注意以下事项：

  • The CREATE SCHEMA command creates a corresponding namespace in your remote catalog only when you use a catalog-linked database.仅当您使用目录链接数据库时，CREATE SCHEMA 命令才会在您的远程目录中创建相应的命名空间。
  • The ALTER and CLONE options aren’t supported.不支持 ALTER 和 CLONE 选项。
  • Delimiters aren’t supported for schema names. Only alphanumeric schema names are supported.模式名称不支持分隔符。仅支持字母数字模式名称。

• You can set a target file size for a table’s Parquet files. For more information, see Set a target file size.您可以为表的 Parquet 文件设置目标文件大小。有关更多信息，请参阅设置目标文件大小。

• For Azure cloud storage services: Snowflake only supports externally managed writes for Iceberg tables that use the following services for external storage:对于 Azure 云存储服务：Snowflake 仅支持对使用以下服务进行外部存储的 Iceberg 表执行外部管理的写入操作：

  • Blob StorageBlob Storage
  • Data Lake Storage Gen2Data Lake Storage Gen2
  • General-purpose v1通用 v1 (General-purpose v1)
  • General-purpose v2通用 v2 (General-purpose v2)
  • Microsoft Fabric OneLakeMicrosoft Fabric OneLake

• Sharing:

  • Sharing with a listing isn’t currently supported.目前不支持通过列表 (listing) 进行共享。
  • Direct sharing isn’t currently supported.目前不支持直接共享。

Access by third-party clients to Iceberg data, metadata第三方客户端对 Iceberg 数据和元数据的访问

• Third-party clients can’t append to, delete from, or upsert data to Iceberg tables that use Snowflake as the catalog.第三方客户端无法向使用 Snowflake 作为目录的 Iceberg 表追加、删除数据或执行更新插入 (upsert) 操作。

Table optimization表优化

• Snowflake doesn’t support orphan file deletion for Snowflake-managed Iceberg tables. If you see a mismatch between storage usage for your external cloud storage and Snowflake, you might have orphan files in your external cloud storage. To see your storage usage for Snowflake, you can use the TABLE_STORAGE_METRICS view or TABLE_STORAGE_METRICS view. If you see a mismatch, contact Snowflake Support for assistance with determining whether you have orphan files and removing them.Snowflake 不支持删除 Snowflake 管理的 Iceberg 表中的孤立文件。如果您发现外部云存储的存储使用量与 Snowflake 统计的数据不一致，则您的外部云存储中可能存在孤立文件。要查看您在 Snowflake 中的存储使用情况，可以使用 TABLE_STORAGE_METRICS 视图。如果发现不一致，请联系 Snowflake 支持部门，以协助确定是否存在孤立文件并将其删除。

• For Snowflake-managed Iceberg tables, if a DML operation fails unexpectedly and rolls back, some Parquet files might get written to your external cloud storage but won’t be tracked or referenced by your Iceberg table metadata. These Parquet files are orphan files.对于 Snowflake 管理的 Iceberg 表，如果 DML 操作意外失败并回滚，某些 Parquet 文件可能会被写入您的外部云存储，但不会被您的 Iceberg 表元数据跟踪或引用。这些 Parquet 文件即为孤立文件。

External query engines through Snowflake Horizon Catalog通过 Snowflake Horizon Catalog 使用外部查询引擎

Native App FrameworkNative App Framework

You can share Iceberg tables with consumers through the Snowflake Native App Framework. Be aware of the following restrictions:您可以通过 Snowflake Native App Framework 与消费者共享 Iceberg 表。请注意以下限制：

• Iceberg tables shared through a Native App are read-only for consumers.通过 Native App 共享的 Iceberg 表对于消费者而言是只读的。
• Cross-Cloud Auto-Fulfillment is not supported for apps that share Iceberg tables.对于共享 Iceberg 表的应用，不支持跨云自动履行 (Cross-Cloud Auto-Fulfillment)。
• Consumers must explicitly enable the EXTERNAL_DATA restricted feature to the app before it can resolve Iceberg tables. For more information, see Request access to external and Apache Iceberg™ tables.消费者必须先为应用显式启用 EXTERNAL_DATA 受限功能，应用才能解析 Iceberg 表。有关更多信息，请参阅“请求访问外部表和 Apache Iceberg™ 表”。

Collation排序规则 (Collation)

For Snowflake-managed Iceberg tables, collation is supported. Use the ICEBERG_DEFAULT_DDL_COLLATION parameter to set a default collation for new string columns. Collation applies only to Snowflake-managed Iceberg tables.对于 Snowflake 管理的 Iceberg 表，支持排序规则。使用 ICEBERG_DEFAULT_DDL_COLLATION 参数为新字符串列设置默认排序规则。排序规则仅适用于 Snowflake 管理的 Iceberg 表。

Unsupported features不支持的功能

The following Snowflake features aren’t currently supported for all Iceberg tables:目前所有 Iceberg 表均不支持以下 Snowflake 功能：

• Hybrid tables混合表 (Hybrid tables)
• Snowflake encryptionSnowflake 加密
• Tagging using the ASSOCIATE_SEMANTIC_CATEGORY_TAGS stored procedure使用 ASSOCIATE_SEMANTIC_CATEGORY_TAGS 存储过程进行标记
• Temporary tables临时表

Fail-safe isn’t supported for Iceberg tables that use a customer-managed external volume. Permanent Iceberg tables that use Snowflake storage (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED) are protected by Fail-safe. Transient tables are supported only with Snowflake storage, and they aren’t protected by Fail-safe. For details, see Permanent and transient tables.对于使用客户管理的外部卷的 Iceberg 表，不支持故障安全 (Fail-safe)。使用 Snowflake 存储 (EXTERNAL_VOLUME = SNOWFLAKE_MANAGED) 的永久 Iceberg 表受故障安全保护。瞬态表仅在 Snowflake 存储下受支持，且不受故障安全保护。有关详细信息，请参阅“永久表和瞬态表”。

The following features aren’t supported for externally managed Iceberg tables:外部管理的 Iceberg 表不支持以下功能：

• Cloning克隆
• Clustering
• Standard and append-only streams. Insert-only streams are supported.标准流和仅追加流。支持仅插入流。
• Replication of Iceberg tables, external volumes, or catalog integrationsIceberg 表、外部卷或目录集成的复制
• Snowflake schema evolutionSnowflake 模式演变 (Schema evolution)