CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

構文¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    [ CATALOG_API_TYPE = PUBLIC ]
    CATALOG_NAME = '<open_catalog_catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    CATALOG_API_TYPE = PRIVATE
    CATALOG_NAME = '<open_catalog_catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

必須パラメーター¶

name

カタログ統合の識別子（名前）を指定する文字列。アカウント内で一意である必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例: "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、 識別子の要件 をご参照ください。

CATALOG_SOURCE = POLARIS

カタログソースとして Snowflake Open Catalog を指定します。

TABLE_FORMAT = ICEBERG

カタログが提供するテーブル形式のApache Iceberg™を指定します。

REST_CONFIG = ( ... )

Open Catalog アカウントとカタログ名に関する情報を指定します。

CATALOG_URI = 'https://open_catalog_account_url'

あなたの Open Catalog アカウント URL。サポートされる値は次のとおりです。

• https://< open_catalog_account_identifier >.snowflakecomputing.com/polaris/api/catalog: CATALOG_API_TYPE = PUBLIC の場合。値の例:

  • https://<組織名>-<使用するSnowflake Open Catalogアカウント名>.snowflakecomputing.com/polaris/api/catalog

  • https://<アカウントロケーター>.<クラウドリージョンID>.<クラウド>.snowflakecomputing.com/polaris/api/catalog

  注釈

  • Snowflakeの組織名（<組織名>）を調べるには、 アカウントの組織名とアカウント名の検索 のステップに従います。

  • <my-snowflake-open-catalog-account-name を見つけるには、 Snowflake Open Catalog ドキュメントにある Snowflake Open Catalogアカウントのアカウント名を見つける をご参照ください。

  • <アカウントロケーター>、 <クラウドリージョンID>、および <クラウド> を検索するには、 形式2: リージョン内のアカウントロケーター をご参照ください。

• https://<open_catalog_privatelink_account_url >/polaris/api/catalog: CATALOG_API_TYPE = PRIVATE の場合。

  注釈

  <open_catalog_privatelink_account_url > には、以下の値のいずれかを入力してください。

  • PrivateLink アカウント URL

  • リージョンレス PrivateLink アカウント URL

  これらの値を取得するには、プライベート接続用のOpen Catalogアカウント設定を取得します。詳細については、Open Catalogアカウントがホストされているクラウドプラットフォームの説明をご参照ください。

  • AWS

  • Azure

CATALOG_API_TYPE = { PRIVATE | PUBLIC }

カタログ API タイプを指定します。SnowflakeとOpen Catalog間の接続をパブリックインターネット経由でルーティングする場合、このパラメーターはオプションです。

• PRIVATE: Snowflake Open Catalogにおけるインバウンドネットワークトラフィックのプライベート接続 を使用している場合、プライベート IP アドレス経由でSnowflakeを Open Catalog に接続します。

• PUBLIC: SnowflakeとOpen Catalogをパブリックインターネット経由で接続します。

デフォルト: PUBLIC

CATALOG_NAME = 'open_catalog_name'

Open Catalog で使用するカタログ名を指定します。

REST_AUTHENTICATION = ( ... )

Snowflake が Open Catalog に接続する際に使用する認証の詳細を指定します。

TYPE = OAUTH

使用する認証タイプとして OAuth を指定します。

OAUTH_CLIENT_ID = 'oauth_client_id'

Open Catalog サービス接続に関連付けられた OAuth2 認証情報のクライアント ID。

OAUTH_CLIENT_SECRET = 'oauth_secret'

Open Catalog サービス接続に関連付けられた OAuth2 認証情報のシークレット。

OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2')

OAuth トークンのスコープ。Iceberg REST API 仕様には1つのスコープしか含まれていないが、カタログは実装において複数のスコープをサポートすることができます。

ENABLED = {TRUE | FALSE}

カタログ統合をIcebergテーブルで使用できるかどうかを指定します。

• TRUE は、ユーザーがこの統合を参照する新しいIcebergテーブルを作成できるようにします。この統合関数を通常参照する既存のIcebergテーブル。

• FALSE は、ユーザーがこの統合を参照する新しいIcebergテーブルを作成できないようにします。この統合を参照する既存のIcebergテーブルは、テーブル定義のカタログにアクセスできません。

オプションのパラメーター¶

CATALOG_NAMESPACE = 'open_catalog_namespace'

• Snowflakeを使用してSnowflake Open Catalogのテーブルをクエリする ためにカタログ統合を作成している場合、オプションで Open Catalog から名前空間を指定できます。Snowflakeは、このカタログ統合に関連付けるすべてのIcebergテーブルにこの名前空間を使用します。

  指定する場合、テーブルを作成する際にテーブルレベルでこの値をオーバーライドできます。指定しない場合は、テーブルの作成時にテーブルレベルで名前空間を設定する必要があります。

• Snowflake Open CatalogでSnowflakeが管理するテーブルを同期する ためにカタログ統合を作成している場合、このパラメーターは Open Catalog でテーブルを同期する方法には影響しません。Snowflakeは、定義済みのルールを使用して、カタログ統合で指定した Open Catalog 内の外部カタログにテーブルを同期します。

  例えば、Snowflakeに db1.public.table1 Icebergテーブルが登録されていて、カタログ統合で catalog1 を指定した場合、Snowflakeは次の完全修飾名を持つ Open Catalog とテーブルを同期します: catalog1.db1.public.table1。

REFRESH_INTERVAL_SECONDS = value

自動リフレッシュ のメタデータ更新のために外部 Iceberg カタログをポーリングしようとする間に Snowflake が待機する秒数を指定します。

デルタベースのテーブルの場合、Snowflakeが外部クラウドストレージに新しいメタデータをポーリングするまでの待機秒数を指定します。

値：30から86400まで。

デフォルト: 30秒

COMMENT = 'string_literal'

統合のコメントを指定する文字列（リテラル）。

デフォルト: 値なし

アクセス制御の要件¶

この操作の実行に使用される ロール には、少なくとも次の 権限 が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意¶

• 既存のカタログ統合は変更できません。代わりに CREATE OR REPLACE CATALOG INTEGRATION ステートメントを使用してください。

• 1つ以上の Apache Iceberg™ テーブルがカタログ統合に関連付けられている場合、カタログ統合をドロップしたり置き換えたりすることはできません。

  カタログ統合に依存するテーブルを表示するには、 SHOW ICEBERG TABLES コマンドと、 catalog_name 列でフィルターする RESULT_SCAN を使用したクエリを使用できます。

  注釈

  列識別子（catalog_name）は大文字と小文字を区別します。SHOW ICEBERG TABLES 出力に表示されるのと同じように、列識別子を指定します。

  例:

  SHOW ICEBERG TABLES;
  
  SELECT * FROM TABLE(
    RESULT_SCAN(
        LAST_QUERY_ID()
      )
    )
    WHERE "catalog_name" = 'my_catalog_integration_1';
  

  Copy

• メタデータについて:

  注意

  Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

• OR REPLACE と IF NOT EXISTS 句は互いに排他的です。両方を同じステートメントで使うことはできません。

• CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

• カタログ統合の作成に関するトラブルシューティングについては、 オープンカタログのカタログ統合が作成できない をご参照ください。

例¶

次の例では、Snowflakeでこの名前空間の下にグループ化されたテーブルをクエリするために、 Open Catalog の内部カタログにある特定の名前空間について、 Open Catalog のカタログ統合を作成します。 Open Catalog の内部カタログに関する情報については、 Open Catalog ドキュメントの カタログタイプ をご参照ください。

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_catalog_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = 'my_catalog_name'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

次の例では、 Open Catalog のカタログ統合を作成し、外部カタログである Open Catalog の customers カタログにSnowflake管理テーブルを同期します。 Open Catalog の外部カタログに関する情報については、 Open Catalog ドキュメントの カタログタイプ をご参照ください。

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int2
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.com/polaris/api/catalog'
    CATALOG_NAME = 'customers'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;