CREATE CATALOG INTEGRATION（对象存储）

Creates a new catalog integration in the account or replaces an existing catalog integration for the following sources:

  • Apache Iceberg™ metadata files
  • Delta Lake metadata files
See also:

ALTER CATALOG INTEGRATION , DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

语法

CREATE [ OR REPLACE ] CATALOG INTEGRATION [IF NOT EXISTS]
  <name>
  CATALOG_SOURCE = OBJECT_STORE
  TABLE_FORMAT = { ICEBERG | DELTA }
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

必填参数

name

用于指定目录集成的标识符（名称）的字符串；在账户中必须唯一。

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case sensitive.

For more information, see Identifier requirements.

CATALOG_SOURCE = OBJECT_STORE

指定外部 Iceberg 元数据文件或对象存储中的 Delta 文件作为源。

TABLE_FORMAT = { ICEBERG | DELTA }

指定表格式。

ENABLED = { TRUE | FALSE }

指定目录集成是否可用于 Iceberg 表。

  • TRUE allows users to create new Iceberg tables that reference this integration. Existing Iceberg tables that reference this integration function normally.
  • FALSE prevents users from creating new Iceberg tables that reference this integration. Existing Iceberg tables that reference this integration cannot access the catalog in the table definition.

The value is case-insensitive.

The default is TRUE.

可选参数

REFRESH_INTERVAL_SECONDS = value

Specifies the number of seconds that Snowflake waits between attempts to poll the external Iceberg catalog for metadata updates for automated refresh.

For Delta-based tables, specifies the number of seconds that Snowflake waits between attempts to poll your external cloud storage for new metadata.

Values: 30 to 86400, inclusive

Default: 30 seconds

Note

The REFRESH_INTERVAL_SECONDS parameter is only supported when TABLE_FORMAT = DELTA for this type of catalog integration.

COMMENT = 'string_literal'

字符串（字面量），用于指定集成注释。

默认：无值

访问控制要求

A role used to execute this operation must have the following privileges at a minimum:

权限对象备注
CREATE INTEGRATION账户Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

使用说明

  • 您无法修改现有目录集成;请改用 CREATE OR REPLACE CATALOG INTEGRATION 语句。

  • You can’t drop or replace a catalog integration if one or more Apache Iceberg™ tables are associated with the catalog integration.

    To view the tables that depend on a catalog integration, you can use the SHOW ICEBERG TABLES command and a query using the pipe operator (->>) that filters on the catalog_name column.

    Note

    The column identifier (catalog_name) is case-sensitive. Specify the column identifier exactly as it appears in the SHOW ICEBERG TABLES output.

    For example:

    SHOW ICEBERG TABLES
  ->> SELECT *
        FROM $1
        WHERE "catalog_name" = 'my_catalog_integration_1';

  • Automatically refresh Apache Iceberg™ tables is only supported for this type of catalog integration when TABLE_FORMAT = DELTA.

  • 关于元数据：

    Attention

    Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

  • The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.

  • CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

示例

The following example creates an integration that uses Iceberg metadata in external cloud storage. OBJECT_STORE corresponds to the object storage that you associate with an external volume.

CREATE CATALOG INTEGRATION myCatalogInt
  CATALOG_SOURCE = OBJECT_STORE
  TABLE_FORMAT = ICEBERG
  ENABLED = TRUE;