Configure a catalog integration for Iceberg tables

A catalog integration is a named, account-level Snowflake object that stores information about how your table metadata is organized for the following scenarios:

  • When you don’t use Snowflake as the Iceberg catalog. For example, you need a catalog integration if your table is managed by AWS Glue.

  • When you want to integrate with Polaris Catalog to:

    • Query an Iceberg table in Polaris Catalog using Snowflake.

    • Sync a Snowflake-managed Iceberg table with Polaris so that third-party compute engines can query the table.

A single catalog integration can support one or more Iceberg tables that use the same external catalog.

You must specify a catalog integration to create an Iceberg table for the following scenarios:

  • Use an external Iceberg catalog.

  • Create a table from files in object storage.

  • Integrate with Polaris Catalog.

  • Use an Iceberg REST catalog.

Create a catalog integration

You can create and configure a catalog integration to use with one or more Iceberg tables.

For specific instructions, see the following topics:

Set a catalog at the account, database, or schema level

To define which catalog to use for Iceberg tables, you can set the CATALOG parameter at the following levels:

Account:

Account administrators can use the ALTER ACCOUNT command to set the parameter for the account. If the value is set for the account, all Iceberg tables created in the account that use an external catalog use this catalog integration by default.

Object:

Users can execute the appropriate CREATE <object> or ALTER <object> command to override the CATALOG parameter value at the database or schema level. The lowest-scoped declaration is used: schema > database > account.

In addition to the minimum privileges required to modify an object using the appropriate ALTER <object_type> command, a role must have the USAGE privilege on the catalog integration.

Note

Changes to the CATALOG parameter only apply to tables created after the change. Existing tables continue to use the catalog integration specified when they were created.

Example

The following statement sets a catalog integration (shared_catalog_integration) for a database named my_database_1:

ALTER DATABASE my_database_1
  SET CATALOG = 'shared_catalog_integration';
Copy

After setting a catalog integration at the database level, you can create an Iceberg table in that database without specifying a catalog integration. The following statement creates an Iceberg table from metadata in object storage in my_database_1 that uses the default catalog integration (shared_catalog_integration) set for the database.

CREATE ICEBERG TABLE my_iceberg_table
   EXTERNAL_VOLUME='my_external_volume'
   METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';
Copy
Language: English