CREATE CATALOG INTEGRATION

Note

A catalog integration is required only when you want to create a read-only Iceberg table with an external catalog or from source files in object storage. You don’t need a catalog integration to create an Iceberg table that uses Snowflake as the Iceberg catalog. To use Snowflake as your catalog, set the CATALOG parameter to SNOWFLAKE in the CREATE ICEBERG TABLE command.

Creates a new catalog integration for Iceberg tables in the account or replaces an existing catalog integration.

See also:

DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

Syntax

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

Where:

catalogParams (for AWS Glue)::=
  GLUE_AWS_ROLE_ARN = '<arn-for-AWS-role-to-assume>'
  GLUE_CATALOG_ID = '<glue-catalog-id>'
  [ GLUE_REGION = '<AWS-region-of-the-glue-catalog>' ]
  CATALOG_NAMESPACE = '<catalog-namespace>'
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 details, see Identifier requirements.

CATALOG_SOURCE = { GLUE | OBJECT_STORE }

Specifies the type of catalog source.

AWS Glue

GLUE: Creates an integration between Snowflake and AWS Glue.

Iceberg metadata in object storage

OBJECT_STORE: Creates an integration for Iceberg metadata files in an external cloud storage location that you associate with an external volume.

TABLE_FORMAT = { ICEBERG }

Specifies the table format supplied by the catalog.

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

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.

Catalog parameters (catalogParams)

AWS Glue

Important

When you create a catalog integration for AWS Glue, you must complete additional steps to establish a trust relationship between Snowflake and the Glue Data Catalog. For details, see Configure a catalog integration for Iceberg tables.

GLUE_AWS_ROLE_ARN = 'arn-for-AWS-role-to-assume'

Specifies the Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role to assume.

GLUE_CATALOG_ID = 'glue-catalog-id'

Specifies the ID of your AWS account.

[ GLUE_REGION = 'AWS-region-of-the-glue-catalog' ]

Specifies the AWS Region of your AWS Glue Data Catalog. You must specify a value for this parameter if your Snowflake account is not hosted on AWS. Otherwise, the default region is the Snowflake deployment region for the account.

CATALOG_NAMESPACE = 'catalog-namespace'

Specifies your AWS Glue Data Catalog namespace (for example, my_glue_database). This is the default namespace for all Iceberg tables that you associate with this catalog integration. You can override this value by specifying the namespace at the table level when you create a table.

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.

  • 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

AWS Glue

The following example creates a catalog integration that uses an AWS Glue catalog source. When you create a catalog integration for Glue, you must complete additional steps to establish a trust relationship between Snowflake and the Glue Data Catalog. For details, see Configure a catalog integration for Iceberg tables.

CREATE CATALOG INTEGRATION glueCatalogInt
  CATALOG_SOURCE=GLUE
  CATALOG_NAMESPACE='my.catalogdb'
  TABLE_FORMAT=ICEBERG
  GLUE_AWS_ROLE_ARN='<arn-for-aws-role-to-assume>'
  GLUE_CATALOG_ID='<catalog-id>'
  GLUE_REGION='<optional-aws-region-of-the-glue-catalog>'
  ENABLED=TRUE;
Copy

Iceberg metadata in object storage

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