CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)¶

Syntax¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<namespace>'
  REST_CONFIG = (
    restConfigParams
  )
  REST_AUTHENTICATION = (
    restAuthenticationParams
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Where:

restConfigParams ::=

  CATALOG_URI = '<rest_api_endpoint_url>'
  [ PREFIX = '<prefix>' ]
  [ WAREHOUSE = '<warehouse_name>' ]
  [ CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY } ]

The restAuthenticationParams are as follows, depending on your authentication method:

OAuth

restAuthenticationParams (for OAuth) ::=

  TYPE = OAUTH
  [ OAUTH_TOKEN_URI = 'https://<token_server_uri>' ]
  OAUTH_CLIENT_ID = '<oauth_client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
  OAUTH_ALLOWED_SCOPES = ('<scope_1>', '<scope_2>')

Bearer token

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  [ SIGV4_SIGNING_REGION = '<region>' ]
  [ SIGV4_EXTERNAL_ID = '<external_id>' ]

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 = ICEBERG_REST

Specifies that the catalog source is a REST catalog that’s compliant with the Apache Iceberg REST specification.

TABLE_FORMAT = ICEBERG

Specifies ICEBERG as the table format supplied by the catalog.

CATALOG_NAMESPACE = 'namespace'

Specifies the namespace in the external catalog. Snowflake uses this namespace for all Iceberg tables that you associate with this catalog integration.

You can override this value by specifying a namespace at the table level using the CATALOG_NAMESPACE parameter for CREATE ICEBERG TABLE (Iceberg REST catalog).

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.

• FALSE prevents users from creating new Iceberg tables that reference this integration.

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.

Values: 30 to 86400, inclusive

Default: 30 seconds

Preview feature

Available to all accounts.

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:

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¶

• Catalog integrations provide read-only access to external Iceberg catalogs.

• You can’t 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 a REST catalog integration that uses OAuth to connect to Tabular. It sets a default namespace using the CATALOG_NAMESPACE parameter.

To override the default namespace at the table level, use the CATALOG_NAMESPACE parameter for CREATE ICEBERG TABLE.

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;

For examples that cover the other authentication options, see Configure a catalog integration for Apache Iceberg™ REST catalogs.