Use a catalog-linked database for Apache Iceberg™ tables¶

With a catalog-linked database, you can access multiple remote Iceberg tables from Snowflake without creating individual externally managed tables.

目录链接的数据库是一种连接到外部 Iceberg REST 目录的 Snowflake 数据库。Snowflake 会自动与外部目录同步以检测命名空间和 Iceberg 表，并将远程表注册到目录链接的数据库。目录链接的数据库还支持创建和删除架构或 Iceberg 表。

Billing for catalog-linked databases¶

Snowflake bills your account for the following usage:

• Automatic table discovery, create schema, drop schema, and drop table. Snowflake will bill your account for this usage under the CREDITS_USED_CLOUD_SERVICES usage type. Usage for cloud services is charged only if the daily consumption of cloud services exceeds 10% of the daily usage of virtual warehouses. For more information, see Understanding billing for cloud services usage.
• Create table. Snowflake will bill your account for this usage under the CREDITS_USED_COMPUTE usage type through auto refresh. The cost for this usage is described in Table 5 of the Snowflake service consumption table on the Snowflake website. Refer to the Snowflake-managed compute column for the Automated Refresh and Data Registration row.

Snowflake won’t bill you for any cloud services that you use during table creation.

在创建目录链接的数据库之前，请从以下选项中选择一种来配置外部目录及表存储的访问权限。

以下步骤介绍如何创建目录链接的数据库、检查 Snowflake 与目录之间的同步状态，以及在数据库中创建或查询表。

1. Configure access to your external catalog and table storage
2. 创建目录链接数据库
3. 检查目录同步状态
4. 对于目录链接的数据库中的 Iceberg 表： or 写入远程目录

Configure access to your external catalog and table storage¶

Before you create a catalog-linked database, you need to configure access to your external catalog and table storage. To configure this access, you configure a catalog integration with vended credentials. With this option, your remote Iceberg catalog must support credential vending.

For instructions, see Use catalog-vended credentials for Apache Iceberg™ tables.

创建目录链接数据库

Create a catalog-linked database with the CREATE DATABASE (catalog-linked) command:

The following example creates a catalog-linked database that uses vended credentials. The sync interval is 30 seconds, which is the default. The sync interval tells Snowflake how often to poll your remote catalog.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int'
  );

Your catalog-linked database includes a link icon.

Check the configuration of a catalog-linked database¶

After you create a catalog-linked database, use the SYSTEM$GET_CATALOG_LINKED_DATABASE_CONFIG function to check the configuration for the database.

SELECT SYSTEM$GET_CATALOG_LINKED_DATABASE_CONFIG('my_linked_db');

检查目录同步状态

To check whether Snowflake has successfully linked your remote catalog to your database, use the SYSTEM$CATALOG_LINK_STATUS function.

该函数还可提供相关信息，帮助您识别远程目录中同步失败的表。

SELECT SYSTEM$CATALOG_LINK_STATUS('my_linked_db');

Identify tables that were created but couldn’t be initialized¶

To identify tables in the remote catalog that synced successfully but fail to refresh automatically, run the SHOW ICEBERG TABLES command, and then refer to the auto_refresh_status column in the output. These tables have an executionState of ICEBERG_TABLE_NOT_INITIALIZED in the output.

For example, Snowflake might successfully discover and create a table in your remote catalog to your catalog-linked database, but this table has a corrupted data file in your remote catalog. As a result, Snowflake can’t automatically refresh the table until you resolve the error.

Automated refresh is turned off for these kinds of tables, so querying the table in Snowflake returns an error that says the table was never initialized. To query the table, you must fix the error, and then turn on automated refresh for the table.

对于目录链接的数据库中的 Iceberg 表：¶

创建目录链接的数据库后，Snowflake 会启动表发现过程，并自动使用 SYNC_INTERVAL_SECONDS 参数值（默认间隔为 30 秒）轮询已链接的目录以检查变更。

在数据库中，远程目录的允许命名空间将显示为架构，而 Iceberg 表将出现在其各自的架构之下。

您可以使用 SELECT 语句查询远程表。

例如：

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;

写入远程目录

您可以使用 Snowflake 在已链接目录中创建命名空间和 Iceberg 表。有关详细信息，请参阅以下主题：

• Write support for externally managed Apache Iceberg™ tables
• Use CREATE SCHEMA to create namespaces in your external catalog
• Create an Iceberg table in a catalog-linked database

Requirements for identifier resolution in a catalog-linked database¶

The requirement for resolving an identifier depends on the following:

• The value that you specified for the CATALOG_CASE_SENSITIVITY parameter when you created your catalog-linked database
• Whether your external Iceberg catalog uses case-sensitive or case-insensitive identifiers.

The following table shows the requirement for each scenario:

CREATE TABLE "Table1" (id INT, name STRING);

SELECT * FROM "Table1";

SELECT * FROM table1;

SELECT * FROM TABLE1;

SELECT * from "s1";
SELECT * from "lowercasetablename";

SELECT * from table1;
SELECT * from TABLE1;
SELECT * from Table1;
SELECT * from "table1";

CREATE SCHEMA My_Schema;

CREATE ICEBERG TABLE My_Schema.My_Table (Col1 INT, Col2 STRING);

ALTER ICEBERG TABLE my_table ADD COLUMN New_Col STRING;

ALTER ICEBERG TABLE my_table RENAME COLUMN col2 TO Aux_Column;

SELECT * from table1;
SELECT * from TABLE1;
SELECT * from Table1;
SELECT * from "Table1";

为 |iceberg-tm| 表使用目录链接的数据库¶

Consider the following items when you use a catalog-linked database: