CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶
新しい カタログ統合 をアカウント内の Snowflake Open Catalog に統合する Apache Iceberg™ テーブル に対して作成するか、既存のカタログ統合を置き換えます。
このコマンドを使用して、 Apache Polaris™ のIcebergテーブルのカタログ統合を作成することもできます。
- こちらもご参照ください。
ALTER CATALOG INTEGRATION、 DROP CATALOG INTEGRATION、 SHOW CATALOG INTEGRATIONS、 DESCRIBE CATALOG INTEGRATION
構文¶
CATALOG_API_TYPE: PUBLIC¶
このカタログ統合を使用して、Snowflakeをパブリックインターネット経由で Open Catalog に接続します。CATALOG_API_TYPE パラメーターのデフォルトは PUBLIC であるため、このパラメーターを指定する必要はありません。
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>' ]
CATALOG_API_TYPE: PRIVATE¶
Snowflake Open Catalogにおけるインバウンドネットワークトラフィックのプライベート接続 を使用している場合は、このカタログ統合を使用して、プライベート IP アドレス経由で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 = 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
の場合。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'
統合のコメントを指定する文字列(リテラル)。
デフォルト: 値なし
アクセス制御の要件¶
この操作の実行に使用される ロール には、少なくとも次の 権限 が必要です。
権限 |
オブジェクト |
注意 |
---|---|---|
CREATE INTEGRATION |
アカウント |
Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed. |
指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。
セキュリティ保護可能なオブジェクト に対して 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';
メタデータについて:
注意
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;