CREATE CATALOG INTEGRATION （Apache Iceberg™ REST）

オープンソースの Apache Iceberg™ REST OpenAPI 仕様 に準拠したリモートカタログで管理される Apache Iceberg™ テーブル 用の新しい カタログ統合 をアカウントに作成するか、既存のカタログ統合を置き換えます。

注釈

Snowflake Open Catalog の統合を作成するには、 CREATE CATALOG INTEGRATION (Snowflake Open Catalog) をご参照ください。

こちらもご参照ください。

ALTER CATALOG INTEGRATION、 DROP CATALOG INTEGRATION、 SHOW CATALOG INTEGRATIONS、 DESCRIBE CATALOG INTEGRATION

構文

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>' ]
Copy

条件:

restConfigParams ::=

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

restAuthenticationParams は、認証方法によって以下のようになります。

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>')
Copy

ベアラー トークン

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'
Copy

SigV4

restAuthenticationParams (for SigV4) ::=

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

パラメーター

name

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

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

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

CATALOG_SOURCE = ICEBERG_REST

カタログソースが Apache Iceberg REST 仕様に準拠した REST カタログであることを指定します。

TABLE_FORMAT = ICEBERG

カタログが提供する表形式として ICEBERG を指定します。

CATALOG_NAMESPACE = 'namespace'

外部カタログの名前空間を指定します。Snowflakeは、このカタログ統合に関連付けるすべてのIcebergテーブルにこの名前空間を使用します。

CREATE ICEBERG TABLE (Iceberg REST カタログ) の CATALOG_NAMESPACE パラメーターを使用してテーブルレベルで名前空間を指定すると、この値をオーバーライドできます。

ENABLED = { TRUE | FALSE }

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

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

  • FALSE は、ユーザーがこの統合を参照する新しいIcebergテーブルを作成できないようにします。

REFRESH_INTERVAL_SECONDS = value

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

値：30から86400まで。

デフォルト: 30秒

プレビュー機能

すべてのアカウントで利用可能です。

COMMENT = 'string_literal'

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

デフォルト: 値なし

REST 構成パラメーター （restConfigParams）

CATALOG_URI = 'rest_api_endpoint_url'

REST API 用のカタログのエンドポイント URL。AWS Glue REST の場合は、 AWS Glue Iceberg REST カタログのサービスエンドポイント を指定します。

PREFIX

オプションで、すべての API ルートに付加するプレフィックスを指定します。

CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY | AWS_GLUE }

API カタログの接続タイプを指定します。SigV4 認証の場合は必須です。それ以外では、このパラメーターはオプションです。

  • PUBLIC は、一般にアクセス可能で、Amazon API Gatewayを使用して管理されていない API を指定します。 SigV4 APIs 以外の場合に使用されます。

  • AWS_API_GATEWAY は、Amazon API Gatewayを使用して管理されるパブリック API を指定します。

  • AWS_PRIVATE_API_GATEWAY は、Amazon API Gatewayを使用して管理されるプライベート API を指定します。

  • AWS_GLUE は、 AWS Glue REST カタログを指定します。このオプションでは、 WAREHOUSE にも値を指定する必要があります。

デフォルト: PUBLIC

WAREHOUSE

リモートカタログサービスにリクエストするウェアハウスの場所（カタログ）または識別子を指定します。

CATALOG_API_TYPE = AWS_GLUE を使用する場合、このパラメーターには AWS アカウントの ID を指定します。

このパラメーターは、一部のサードパーティカタログサービスで必要です。ウェアハウスを指定しなければならないかどうかについては、カタログプロバイダーに確認してください。

REST 認証パラメーター （restAuthenticationParams）

OAuth

TYPE = OAUTH

Iceberg REST カタログへの接続に使用する Snowflake の認証タイプとして OAuth を指定します。

OAUTH_TOKEN_URI = token_server_uri

サードパーティIDプロバイダーの任意 URL。指定しない場合、Snowflake はリモートカタログプロバイダーが OAuth ID プロバイダーであると仮定します。

OAUTH_CLIENT_ID = oauth_client_id

あなたの OAuth2 クライアント ID。

OAUTH_CLIENT_SECRET = oauth_client_secret

あなたの OAuth2 クライアントシークレット。

OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2' )

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

ベアラー トークン

TYPE = BEARER

Snowflake が Iceberg REST カタログに接続する際に使用する認証タイプとして、ベアラートークンを指定します。

BEARER_TOKEN = bearer_token

ID プロバイダーのベアラートークン。個人アクセストークン（PAT）を指定することもできます。

SigV4

TYPE = SIGV4

Iceberg REST カタログに接続するために Snowflake が使用する認証タイプとして、Signature Version 4 を指定します。

SIGV4_IAM_ROLE = 'iam_role_arn'

API Gatewayで REST API にアクセスする権限を持つ IAM ロールのAmazon Resource Name （ARN） を指定します。

SIGV4_SIGNING_REGION = 'region'

オプションで、 API Gatewayの API に関連する AWS Region を指定します。このパラメーターを指定しない場合、SnowflakeはSnowflakeアカウントがデプロイされているリージョンを使用します。

SIGV4_EXTERNAL_ID = 'external_id'

オプションで、Snowflakeが AWS との信頼関係を確立するために使用する外部 ID を指定します。このカタログ統合用に構成した IAM ロールの信頼ポリシーで、同じ外部 ID を指定する必要があります。

このパラメーターに値を指定しない場合、Snowflakeはカタログ統合を作成（または置換）する際に、一意の外部 ID を自動的に生成します。

外部 IDs の詳細情報については、 第三者に AWS リソースへのアクセスを許可する場合に外部 ID を使用する方法 をご参照ください。

アクセス制御の要件

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

権限

オブジェクト

メモ

CREATE INTEGRATION

アカウント

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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

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

使用上の注意

  • カタログ統合は、外部 Iceberg カタログへの読み取り専用アクセスを提供します。

  • 既存のカタログ統合は変更できません。代わりに 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のメタデータフィールド をご参照ください。

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

例

以下の例では、 OAuth を使用して Tabular に接続する REST カタログ統合を作成しています。 CATALOG_NAMESPACE パラメーターを使用して、デフォルトの名前空間を設定します。

テーブルレベルでデフォルトの名前空間をオーバーライドするには、 CREATE ICEBERG TABLE の CATALOG_NAMESPACE パラメーターを使用します。

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;
Copy

SigV4 認証で AWS Glue REST のカタログ統合を作成します。

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'rest_catalog_integration'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    WAREHOUSE = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;
Copy

その他の認証オプションを網羅する例については、 Apache Iceberg™ REST カタログのカタログ統合を構成する をご参照ください。

言語: 日本語