CREATE CATALOG INTEGRATION (Object storage)¶

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

  • Apache Iceberg™ metadata files

  • Delta table files

See also:

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

Syntax¶

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

Required parameters¶

name

String that specifies the identifier (name) for the catalog integration; must be unique in your account.

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

Specifies external Iceberg metadata files or Delta files in object storage as the source.

TABLE_FORMAT = { ICEBERG | DELTA }

Specifies the table format.

  • ICEBERG: Specifies Glue Iceberg tables or Iceberg tables from metadata in an external cloud storage location.

  • DELTA: Specifies Delta tables.

    Preview feature

    Iceberg tables created from Delta tables files are in preview and available to all accounts.

ENABLED = { TRUE | FALSE }

Specifies whether the catalog integration is available to use for Iceberg tables.

  • 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.

Optional parameters¶

COMMENT = 'string_literal'

String (literal) that specifies a comment for the integration.

Default: No value

Access control requirements¶

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

Privilege

Object

Notes

CREATE INTEGRATION

Account

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.

Usage notes¶

  • You cannot modify an existing catalog integration; use a CREATE OR REPLACE CATALOG INTEGRATION statement instead.

  • 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 RESULT_SCAN 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 TABLE(
  RESULT_SCAN(
      LAST_QUERY_ID()
    )
  )
  WHERE "catalog_name" = 'my_catalog_integration_1';
    Copy

  • Regarding metadata:

    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.

  • 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.

Examples¶

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;
Copy
Language: English