Apache Iceberg表の問合せ

Autonomous AI Databaseでは、Apache Iceberg表の問合せがサポートされています。

Apache Iceberg表の問合せについて

Autonomous AI Databaseでは、Apache Iceberg表の問合せがサポートされています。

サポートされる構成

サポートされている構成の互換性マトリックスを次に示します。

カタログ	オブジェクト・ストア	カタログ認証(REST)	ストレージ認証	ノート
Unity (Databricks)	Amazon S3、Azure ADLS Gen2	OAuth2サービス・プリンシパル(/oidc/v1/token) - 推奨、PAT - クイック・テスト	S3アクセス/シークレット・キー、ADLS Gen2 SASキー	{::nomarkdown}<ul> <li><p>UniFormは、Iceberg-readableとして公開されるDelta表でサポートされます。ネイティブIceberg表は、Databricks Unity Catalog Iceberg RESTを介してサポートされます。Icebergのネイティブ表には、Databricks Unity Catalog Iceberg RESTエンドポイントを使用します。
…/api/2.1/unity-catalog/iceberg-rest</p></li><li>オブジェクト・ストア資格証明の販売はサポートされていません。</li> </ul> {:/}
ポラリス(スノーフレーク)	Amazon S3、Azure ADLS Gen2	OAuth2 (クライアント資格証明)またはPolarisでサポートされているトークン	S3アクセス/シークレット・キー、ADLS Gen2 SASキー	オブジェクト・ストア資格証明の自動販売はサポートされていません。
AWS Glue	Amazon S3	該当なし(AWSアカウント認証を使用)	S3アクセス/秘密鍵。	オブジェクト・ストア資格証明の自動販売はサポートされていません。S3およびGlueには同じ資格証明を使用する必要があります。S3とGlueは同じAWSリージョンに存在する必要があります。
JSONメタデータ(カタログ外オプション)	Amazon S3、Azure ADLS Gen2、OCI Object Store	該当なし(RESTなし)	S3アクセス/シークレット・キー、ADLS Gen2 SASキー、OCIネイティブ資格証明	表の`metadata.json` (ルート・マニフェスト)にADBをポイントします。Point-in-Timeスナップショット。スキーマの変更または新しいスナップショットの後に外部表を再作成します。
Hadoop (カタログ外)	OCIオブジェクト・ストレージ	該当なし(RESTなし)	OCIネイティブ資格情報	データおよびメタデータ・ファイルを含むレイクハウス・フォルダを指します。

ノート

ノート: IcebergのOCIリソース・プリンシパルの認証は現在サポートされていません。

デルタ・レイクUniForm表

Autonomous AI Database Serverlessは、UniFormが有効になっている(以前はDelta Lake Universal Formatと呼ばれていた)デルタ・レイク表を問い合せることもできます。UniFormはDelta表のApache Icebergメタデータを書き込むため、そのIcebergメタデータ(IcebergカタログまたはIcebergルート・メタデータ・ファイル経由)に対してAutonomous AI Databaseに外部表を作成し、他のIceberg表と同様に問い合せることができます。このページにも同じ制限があります。UniFormを有効にするには、Delta Lakeのドキュメントを参照してください。

Apache Iceberg表の問合せの制限事項

この章では、Apache Iceberg表の問合せの制限事項を示します。

カタログと相互運用性

Unity Native Iceberg (REST): サポートされていません。

回避策: Unity CatalogのIceberg RESTエンドポイントを介してIceberg可読ビューを公開するには、Delta + UniFormを使用します。
認定RESTカタログ: ADBは、Iceberg読取りアクセスのSnowflake PolarisおよびDatabricks Unity Catalog (UniFormのみ)で認定されています。

認証および資格証明:

カタログ資格証明の販売: サポートされません。

自動ロール仮定やSTSによって発行された一時資格証明など、クラウドネイティブのロールベースの自動販売はサポートされていません。明示的なアクセス/秘密鍵または静的トークンを使用します。)
AWS ARN資格証明: サポートされていません。 ARNを介したIAMロールARNおよびAssumeRoleは受け入れられません。

表セマンティクスおよびDML

パーティション化されたIceberg表はサポートされていません。パーティション化されていない表のみが許可されます。
行レベルの更新(merge-on-read):サポートされません。Icebergメタデータがファイルを削除する場合、クエリーは失敗します。

スキーマとメタデータの進化

固定外部表のスキーマは、作成時に決定され、メタデータのIcebergスキーマ・バージョンと一致する必要があります。Icebergスキーマが更新された場合は、外部表を再作成する必要があります。

スナップショットとタイムトラベル

問合せ時の時間移動なし:スナップショット、バージョンまたはタイムスタンプによる問合せはサポートされていません。
カタログ外のみ:新しいスナップショットは自動的に取得されません。特定のスナップショットを読み取るには、そのスナップショットのmetadata.jsonをターゲットにし、外部表を再作成します。

AWS Glue

資格証明の位置合せ: AWS S3およびAWS Glueには、同じ資格証明を使用する必要があります。
リージョンの共存: S3バケットとAWS Glueカタログは同じAWSリージョンに存在する必要があります。

Apache Iceberg表の問合せに関連する概念

次の概念を理解すると、Apache Iceberg表の問合せに役立ちます。

Icebergカタログ

Icebergカタログは、表メタデータ(表スナップショット、表スキーマおよびパーティション化情報など)を管理するサービスです。Iceberg表の最新のスナップショットを問い合せるには、問合せエンジンはまずカタログにアクセスし、最新のメタデータ・ファイルの場所を取得する必要があります。AWS Glue、Hive、Nessie、Hadoopなど、使用可能なカタログ実装はすでに数多くあります。自律型AIデータベースは、AWS Glueカタログと、Sparkで使用されるHadoopCatalog実装をサポートしています。

詳細は、「optimistic Concurrency」を参照してください。

メタデータ・ファイル

メタデータ・ファイルは、表スナップショット、パーティション化スキームおよびスキーマ情報を追跡するJSONドキュメントです。メタデータ・ファイルは、マニフェスト・リストおよびマニフェスト・ファイルの階層へのエントリ・ポイントです。マニフェストは、パーティショニングやカラム統計などの情報とともに、テーブルのデータファイルを追跡します。詳細は、Iceberg Table Specificationを参照してください。

トランザクション

Icebergは、copy-on-writeまたはmerge-on-readのいずれかを使用して、表に対する行レベルの更新をサポートしています。Copy-on-writeは、更新された行を反映する新しいデータファイルを生成しますが、merge-on-readは、読取り中にデータファイルとマージする必要がある新しい削除ファイルを生成します。Oracleはcopy-on-writeをサポートしています。削除ファイルが見つかった場合、氷山表に対する問合せは失敗します。詳細は、RowLevelOperationModeを参照してください。

スキーマ展開

Icebergはスキーマの進化をサポートしています。スキーマの変更は、スキーマIDを使用してIcebergメタデータに反映されます。Oracle外部表には固定スキーマがあり、表の作成時に最新のスキーマ・バージョンによって決定されます。問合せ対象のメタデータが、表作成時に使用したものと比較して異なるスキーマ・バージョンを指している場合、Iceberg問合せは失敗します。詳細は、Schema Evolutionを参照してください。

パーティション化

Icebergは、隠れたパーティション化や、コストのかかるデータ・レイアウトの変更なしに表のメタデータの処理/変更に依存するパーティションの進化などの高度なパーティション化オプションをサポートしています。

Icebergの設定要件

このトピックでは、IcebergをOracle Autonomous AI Databaseとともに使用するための設定要件について説明します。

Icebergの資格証明: RESTカタログとオブジェクト・ストア

このトピックでは、Apache Icebergが、RESTカタログとオブジェクト・ストアの2つの資格証明を使用してデータを管理およびアクセスする方法について説明します。また、Apache Icebergなどのデータ・レイク表形式で表情報を管理する2つの異なる方法を参照することもできます。

カタログ管理の外部表とダイレクト・メタデータの外部表

次の項では、カタログ管理の外部表をダイレクト・メタデータ外部表と比較し、主な違いを強調表示します。

カタログ管理(Unity/Polaris/AWS Glue)

内容:メタデータ、スキーマおよび現在のスナップショットは、RESTカタログを介して解決されます。

動作:カタログの最新のスナップショット(集中化された権限、タグおよび系統)を自動的に反映します。

最適な対象:エンタープライズ・データ製品、クロスエンジン共有、一貫したガバナンス、発見性(カタログは信頼できる唯一の情報源です)。
- ダイレクト・メタデータ(metadata.jsonを介したファイル・システム)
  
  内容:外部表は、特定のmetadata.jsonを直接指します。
  
  動作:修正された再現可能なスナップショット。自動昇格なし。ガバナンスはオブジェクトストアACLに限定されます。
  
  最適な対象:実験、テスト、監査。

RESTとオブジェクト・ストアの資格証明

RESTカタログ資格証明

Apache Iceberg RESTカタログに接続する場合は、REST資格証明が必要です。RESTカタログは、RESTfulエンドポイントを公開してIceberg表のメタデータを管理します。認証のために、REST資格証明はOAuthベースであることが多いため、client IDおよびsecretを使用してトークン・エンドポイントからベアラー・トークンを取得する必要があります。

REST Icebergカタログを使用する場合は、次の2つの資格証明が必要です。

rest_auth_cred: カタログ・サービス(UnityやPolarisなど)で認証されます。
credential_name: Icebergのデータおよびメタデータが存在するオブジェクト・ストアに対して認証します。

ノート

ノート:現時点では、資格証明の自動送信はサポートされていません。資格証明の自動送信とは、アクセス資格証明(ユーザー名、パスワード、APIキー、トークンなど)が必要になったときに(多くの場合、自動的にまたはオンデマンドで)配布またはフェッチする制御されたプロセスを指します。これは、資格証明を構成ファイルやスクリプトに静的に格納するのではありません。

オブジェクト・ストア資格情報

オブジェクト・ストア資格証明は、Apache Iceberg表がOracle Cloud Infrastructure (OCI) Object StorageやAmazon S 3などのクラウド・オブジェクト・ストレージに直接格納されている場合に使用されます。

資格証明により、Autonomous AI Databaseは、クラウド・オブジェクト・ストアから直接ファイル(Parquetデータやメタデータ・マニフェストなど)にアクセスして読み取ることができます。

ノート

ノート: OCIまたはS3バケットのParquetまたはメタデータ・ファイルを直接指す外部表を定義する場合は、オブジェクト・ストア資格証明を使用します。

前提条件: Iceberg操作のためのネットワーク・アクセス制御リスト(ACL)の付与

このトピックでは、Apache Iceberg文を実行するデータベース・スキーマにネットワーク・アクセス制御リスト(ACL)権限を付与する方法について説明します。

Oracle Database 23aiでApache Iceberg表を問い合せる前に、ネットワーク・アクセス権限を構成する必要があります。Icebergの操作は、HTTPSを介して外部サービスと通信します。これには、システムHTTPプロキシ、カタログ・サービス・エンドポイント、Amazon S3やOCI Object Storageなどのオブジェクト・ストレージ・リポジトリが含まれます。

これらの接続を許可するには、Iceberg問合せまたはData Definition Language (DDL)文を実行するデータベース・スキーマにネットワーク・アクセス制御リスト(ACL)を付与します。必要なACLが付与されていない場合、操作はORA-20000: Failed to generate column list、ORA-24247: network access denied by access control list (ACL)などのエラーで失敗します。

これらのACLは、次のものに付与する必要があります。

Iceberg外部表を作成して所有するスキーマには、必要なホスト名へのアウトバウンドHTTPSアクセスが必要です。
既存のIceberg外部表に対してSELECT文のみを実行する必要があるユーザーには、これらのACLは必要ありません。表に対するDWROLEやSELECTなどの標準権限のみが必要です。

ACLを定義するためのベストプラクティスは、できるだけ制限的なものにし、HTTPS (ポート443)に制限し、Icebergが要求する特定のホストにのみアクセスできるようにすることです。たとえば、Iceberg表にOCIオブジェクト・ストレージにメタデータおよびデータファイルが格納されている場合は、次の手順を使用します。

BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => 'objectstorage.<region>.oraclecloud.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list   => xs$name_list('http'),
                           principal_name   => '<schema>',
                           principal_type   => xs_acl.ptype_db
                        )
   );
END;
/

OCIリージョンで<schema>名および<region>に適切な値を指定します。

この例では、OCIオブジェクト・ストレージ・エンドポイントへのアウトバウンドHTTPSリクエストを行うためのOracleデータベース・スキーマ権限を付与します。

DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACEプロシージャは、ポート上のOCIオブジェクト・ストレージのリージョナル・エンドポイントに接続するときに、指定されたスキーマがhttp権限(HTTPSを含む)を使用できるようにするアクセス制御エントリ(ACE)を追加します。

このアクセスは、Iceberg表メタデータの読取りおよびOCIオブジェクト・ストレージに格納されているデータ・ファイルの取得に必要です。

詳細は、DBMS_NETWORK_ACL_ADMINを参照してください。

構成別ホスト名

次の表をガイドとして使用して、DBMS_CLOUD.CREATE_EXTERNAL_TABLEを実行するスキーマのACLエントリが通常必要となるホスト名を特定します。

ストレージ	ホスト名
OCIオブジェクト・ストレージ(外部カタログまたはHadoopCatalogなし)	`objectstorage.<region>.oraclecloud.com`
AWS S3 (外部カタログなし)	`<bucket>.s3.<region>.amazonaws.com`
AWS Glueカタログ+ S3	`glue..amazonaws.com (catalog API)` `.s3.amazonaws.com (bucket region lookup)` `.s3..amazonaws.com (data and metadata files)`
Databricks Unity Catalog + Azure(ADLS Gen2)	`.azuredatabricks.net (catalog and token endpoints)` `.blob.core.windows.net (data and metadata files)`
Databricks Unityカタログ+ S3	`.azuredatabricks.net` `.s3.amazonaws.com` `.s3..amazonaws.com`
スノーフレークポラリス+ S3	`.snowflakecomputing.com` (Polarisおよびトークン・エンドポイント) `.s3.amazonaws.com` `.s3..amazonaws.com`
Snowflake Polaris + Azure(ADLS Gen2)	`.snowflakecomputing.com` `.blob.core.windows.net`

HTTPSプロキシを使用する場合は、プロキシ・ホストのACLも構成する必要があります。詳細は、Autonomous AI DatabaseからのWebサービスのコールを参照してください。

Iceberg操作のスキーマ・ロールの付与

DWROLEは、Iceberg外部表を作成または管理するすべてのスキーマに付与する必要があります。

Autonomous AI Databaseでは、DWROLEは、DBMS_CLOUDパッケージを使用してデータ・ロードおよび関連操作を実行するための標準権限セットです。このロールを割り当てると、クラウド・ストレージにアクセスし、Iceberg外部表を作成、問合せおよび管理するために必要な権限がスキーマに付与されます。

Apache Iceberg表の問合せの一般的なワークフロー

Apache Icebergテーブルのクエリーを開始する前に、そのワークフローについて理解しておく必要があります。この項では、エンドツーエンドの設定ワークフローとして提示されるデータにアクセスするための外部表の設定方法を5つの主なステップで説明します。

アクセス・モデルの決定:
- カタログ管理: このモデルは、継続的に更新され、管理されたカタログがデータ・メタデータの信頼できる唯一の情報源として機能する場合に使用します。この中央カタログは、データの一貫性とガバナンスの維持に役立ちます。
- ダイレクト・メタデータ: (metadata.jsonを介して)メタデータの固定スナップショットを操作する場合、このモデルを使用します。このモデルは、よりシンプルですが静的であり、自動更新およびガバナンスがないため、本番にはお薦めしません。
必要なものの収集:
- カタログ管理: カタログ・エンドポイント(該当する場合)、正確な表パスおよび実際のデータファイルが存在するオブジェクト・ストアの場所にアクセスできる必要があります。
- Direct-Metadata: ルートmetadata.jsonファイルを指すURIと、これらのデータファイルのオブジェクト・ストアの場所のみが必要です。
資格情報の準備:
- カタログ管理設定の場合、カタログにアクセスするための資格証明を取得します。
- オブジェクト・ストア資格証明は、データ・ファイルとメタデータ・ファイルの両方を読み取るモデルに関係なく、常に必要です。

ノート

ノート:自動資格証明の自動販売およびカタログ・アクセス用のAWS AssumeRoleはサポートされていません。

外部表の作成:
- カタログ管理では、表はカタログを介してデータを問い合せ、オブジェクト・ストア内のファイルにアクセスします。
- Direct-Metadataでは、表はカタログの関与なしに特定のmetadata.jsonファイルを直接指します。
クイック・チェックと期待事項:

COUNT(*)などの単純な問合せを実行して、表の設定を確認し、データに正しくアクセスできることを確認します。

プロバイダのクイックスタート

この章では、様々なクラウド・データ・プロバイダで外部データ・アクセスを設定するプロセスについて説明します。

Databricks Unityカタログ

この項では、DatabricksをUniFormを介してオープン・テーブル・フォーマットにリンクするワークフローについて説明し、Icebergをサポートする環境でのDelta Lakeデータへのアクセスを容易にします。

Databricks Unityカタログ(UniFormパス)

前提条件

Icebergクライアントがそれを読み取ることができるように、UniFormで作成されたDeltaテーブル。
Azure ADLS Gen2またはAWS S3の表ファイル。
外部アクセス用のUnity Catalog権限(外部データ・アクセスの有効化など)。プリンシパルにEXTERNAL USE SCHEMAを付与します。
Auth: OAuth2 (recommended)または個人アクセス・トークン(クイック・テスト用)。
ネットワークACLの構成: Azure Blob Storageに格納されたデータでDatabricks Unity Catalogを使用する外部表を作成する前に、必要なAzureサービスにアウトバウンドHTTPS接続を行う権限をOracleスキーマに付与する必要があります。Oracle AI Databaseではデフォルトでネットワーク・アクセスがブロックされるため、スキーマがアクセスできるようにネットワーク・アクセス制御リスト(ACL)を更新する必要があります。
- Unity Catalog APIおよびトークン/認証エンドポイントをホストするDatabricksワークスペース。
- Azure Storageアカウント。Icebergテーブルのメタデータとデータファイルを保存します。
ネットワークACLを構成する例

BEGIN

   -- Databricks workspace (Unity Catalog and token endpoint)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<workspace>.azuredatabricks.net',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );


   -- Azure Storage (metadata and data files)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<storage-account>.blob.core.windows.net',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );
END;
/

次のプレースホルダを置き換えます。

<workspace>: Azure Databricks URLで使用されるDatabricksワークスペース名。
<storage-account>: Icebergメタデータおよびデータ・ファイルを含むAzure Storageアカウント名。
<schema>: DBMS_CLOUD.CREATE_EXTERNAL_TABLEを実行し、HTTPSアクセスを必要とするOracleスキーマ。

ノート

ノート: Iceberg RESTを介したNative Icebergは、まだ統合ではサポートされていません。Delta with UniForm (Iceberg-readable)を使用してUnity Iceberg REST: https://<workspace-host>/api/2.1/unity-catalog/icebergを介して公開します。

DatabricksでUniForm (Iceberg-readable)表を作成します。

次のプロシージャは、指定されたUnity Catalogカタログおよびスキーマ内のDatabricksに、customers_icebergという名前のUniForm (Iceberg-readable)表を作成します。

USE CATALOG <your_catalog>;
USE SCHEMA  <your_schema>;

CREATE TABLE customers_iceberg (
  id   INT,
  name STRING
)
TBLPROPERTIES(
  'delta.columnMapping.mode'='name',
  'delta.enableIcebergCompatV2'='true',
  'delta.universalFormat.enabledFormats'='iceberg'
);

INSERT INTO customers_iceberg (id, name) VALUES
  (1,'Alice'), (2,'Bob'), (3,'Carol');

オブジェクト・ストア資格証明(ADLS Gen2)

次の手順では、セキュアな外部クラウド・ストレージ・アクセスのためにストレージ・アカウント・キーまたはSASトークンのいずれかを使用して、オブジェクト・ストア・アクセス(Azure Data Lake Storage Gen2)の資格証明を設定します。

BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('AZURE_BLOB_CRED'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'AZURE_BLOB_CRED',
    username        => '<storage-account-or-sas-username>',
    password        => '<storage-key-or-sas-token>'
  );
END;
/

OAuth2でのRESTカタログ資格証明の作成

次のプロシージャは、Databricksサービス・プリンシパル(クライアントIDおよびシークレット)を使用したセキュアな認証のためのOAuth2資格証明を設定します。

-- Databricks service principal (client_id / client_secret)
BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('UNITY_OAUTH'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'UNITY_OAUTH',
    username        => '<client_id>',
    password        => '<client_secret>'
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_ICEBERG',
    credential_name => 'AZURE_BLOB_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg-rest",
        "protocol_config": {
          "iceberg_catalog_type": "unity",
          "rest_catalog_endpoint": "https://<workspace-host>/api/
2.1/unity-catalog/iceberg",
          "rest_authentication": {
            "rest_auth_cred": "UNITY_OAUTH",
            "rest_auth_endpoint": "https://<workspace-host>/oidc/v1/token"
          },
          "table_path": ["<your_catalog>","<your_schema>","customers_iceberg"]
        }
      }
    }'
  );
END;
/
SELECT COUNT(*) FROM CUSTOMERS_ICEBERG;

個人アクセス・トークン(PAT)を使用したRESTカタログ資格証明の作成

この手順では、PAT資格証明を作成し、それを使用して外部表を作成することにより、PATをクイック・テストに使用する方法を示します。

BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('UNITY_PAT'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'UNITY_PAT',
    username        => 'token',
    password        => '<dapiXXXXXXXXXXXXXXXXXXXXXXXX>'
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_ICEBERG',
    credential_name => 'AZURE_BLOB_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg-rest",
        "protocol_config": {
          "iceberg_catalog_type": "unity",
          "rest_catalog_endpoint": "https://<workspace-host>/api/2.1/unity-catalog/iceberg",
          "rest_authentication": { "rest_auth_cred": "UNITY_PAT" },
          "table_path": ["<your_catalog>","<your_schema>","customers_iceberg"]
        }
      }
    }'
  );
END;
/
SELECT COUNT(*) FROM CUSTOMERS_ICEBERG;

スノーフレークポラリス

このトピックでは、OAuth2認証を使用してREST APIを介してApache Polaris Iceberg表へのセキュア・アクセスを許可するSnowflake Polaris (RESTカタログ)について説明します。

Snowflake Polaris (RESTカタログ)

前提条件

Polaris Icebergのカタログとエンドポイントがアカウントで利用可能です。
オブジェクト・ストアでアクセス可能な表ファイル(該当する場合はS3/ADLS)。
Auth: OAuth2推奨(クライアント資格証明)またはPolarisでサポートされている別のトークン・メカニズム。

SnowflakeおよびAmazon S3に格納されているIcebergカタログにアクセスする外部表を作成する前に、データベース・スキーマがそれらのサービスへのアウトバウンドHTTPS接続を許可されている必要があります。Oracle AI Databaseでは、デフォルトでネットワーク・アクセスが制限されるため、スキーマがアクセスできるようにネットワーク・アクセス制御リスト(ACL)を更新する必要があります。

カタログ・アクセス、認証およびトークン交換に使用されるSnowflakeアカウント・エンドポイント
Icebergメタデータおよびデータファイルが格納される Amazon S3リージョナルエンドポイント
(オプション)一部のAWS APIおよびリージョン・ルックアップ操作で必要な非リージョンS3エンドポイント

ネットワークACLを構成する例

BEGIN


   -- Allow HTTPS access to your Snowflake account (Polaris and token endpoints)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<account>.snowflakecomputing.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );


   -- Allow HTTPS access to the S3 bucket (regional endpoint for data/metadata)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<bucket>.s3.<region>.amazonaws.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );


   -- Optional: non-regional S3 endpoint (used for some APIs/region lookup)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<bucket>.s3.amazonaws.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );

END;
/

次のプレースホルダを置き換えます。

<account>: スノーフレーク・アカウント識別子。
<schema>: アウトバウンドHTTPSアクセスを必要とするスキーマ。
<bucket>: Icebergのデータおよびメタデータを含むAmazon S3バケットの名前。
<region>: S3バケットがホストされるAWSリージョン。

OAuth2資格証明の作成:

次の手順では、Apache Polaris Icebergカタログへのアクセスを認証するために、POLARIS_OAUTHという名前のOAuth2資格証明を作成します。

BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('POLARIS_OAUTH'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'POLARIS_OAUTH',
    username        => '<client_id>',
    password        => '<client_secret>'
  );
END;
/

ストレージ資格証明の作成

次の手順では、AWSアクセス・キーIDおよびシークレット・アクセス・キーを使用してオブジェクト・ストレージ(例: Amazon S3)にアクセスするためのS3_CREDという名前のストレージ資格証明を作成します。

-- Storage credential for your object store (example: S3)
BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('S3_CRED'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'S3_CRED',
    username        => '<aws_access_key_id>',
    password        => '<aws_secret_access_key>'
  );
END;
/

外部表の作成

次の手順では、Polarisカタログによって管理されるIceberg形式を使用して格納されたデータにアクセスするAutonomous AI Databaseの<external_table_name>という外部表を定義します。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => '<external_table_name>',
    credential_name => 'S3_CRED',
    format          => q'[
{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "polaris",
      "rest_catalog_prefix": "<polaris_catalog_name>",
      "rest_catalog_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog",
      "rest_authentication": {
        "rest_auth_cred": "POLARIS_OAUTH",
        "rest_auth_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens"
      },
      "table_path": ["<my_namespace>", "<my_table>"]
    }
  }
}
]',
  );
END;
/

Snowflake Polaris Open Catalog UIの例: これは、Snowflake Polaris Open Catalog UI、ネームスペースSALES_NSおよび表SALESを含むメイン・カタログを示しています。

![Description of adbs_polaris_main_ui.png follows](images/adbs_polaris_main_ui.png " ")

[Description of the illustration adbs_polaris_main_ui.png](img_text/adbs_polaris_main_ui.html)

例: この例では、スクリーンショットabovrに示すように、Autonomous AI DatabaseにSALES_POLARIS_EXT外部表を作成します。この表は、PolarisのmainカタログのSALES_NSネームスペースのSALES表に直接接続します。これにより、外部リソースとしてPolaris表にアクセスできます。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'SALES_POLARIS_EXT',
    credential_name => 'S3_CRED',
    format          => q'[
{
  "access_protocol": {
    "protocol_type": "iceberg",
    "protocol_config": {
      "iceberg_catalog_type": "polaris",
      "rest_catalog_prefix": "main",
      "rest_catalog_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog",
      "rest_authentication": {
        "rest_auth_cred": "POLARIS_OAUTH",
        "rest_auth_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens"
      },
      "table_path": ["SALES_NS", "SALES"]
    }
  }
}
]'
  );
END;
/

クイック機能チェック

次のプロシージャは、問合せを実行して、外部表が正しく設定され、アクセス可能であることを確認します。

SELECT COUNT(*) FROM SALES_POLARIS;

ノート

ノート:エンドポイントおよびトークンURLプレースホルダは、Polaris構成によって異なるため、保持してください。

AWS Glueカタログ

このトピックでは、AWS資格情報を使用して、登録済みのIcebergテーブルでGlue Data Catalog経由で Amazon S3データにアクセスする方法について説明します。

前提条件

Iceberg表が登録されているGlueデータ・カタログ(アクセス可能なS3オブジェクト)。

Glueのリージョン名(例: us-east-1)。
Auth: S3のアクセス・キー/シークレット。カタログ構成を介した接着アクセス。
AWS ARNによる資格情報の送信はサポートされていません。明示的な資格証明を指定する必要があります。
AWS GlueをIcebergカタログとして使用し、Amazon S3をストレージ・レイヤーとして使用する外部表を作成する前に、OracleスキーマにこれらのAWSサービスへのアウトバウンドHTTPSリクエストを行う権限が付与されている必要があります。Oracle AI Databaseでは、デフォルトでネットワーク・アクセスが制限されるため、スキーマがアクセスできるようにネットワーク・アクセス制御リスト(ACL)を更新する必要があります。
- IcebergカタログAPIを提供するAWS Glue
- S3リージョナル・エンドポイント。Icebergメタデータおよびデータ・ファイルが格納されます。
- 特定のAWS APIおよびリージョン・ルックアップ操作に必要な非リージョナルS3エンドポイント
ネットワークACLを構成する例

BEGIN


   -- AWS Glue (catalog API)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => 'glue.<region>.amazonaws.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );


   -- S3 bucket (regional endpoint for data and metadata files)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<bucket>.s3.<region>.amazonaws.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );


   -- Optional: non-regional S3 endpoint (used for some APIs or region lookup)
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
      host           => '<bucket>.s3.amazonaws.com',
      lower_port     => 443,
      upper_port     => 443,
      ace            => xs$ace_type(
                           privilege_list => xs$name_list('http'),
                           principal_name => '<schema>',
                           principal_type => xs_acl.ptype_db
                        )
   );

END;
/

次のプレースホルダを置き換えます。

<region>: GlueおよびS3バケットが配置されているAWSリージョン。
<bucket>: Icebergのデータおよびメタデータ・ファイルを格納するS3バケットの名前。
<schema>: DBMS_CLOUD.CREATE_EXTERNAL_TABLEを実行し、HTTPSアクセスを必要とするOracleスキーマ。

ストレージ資格証明を作成します。

次の手順では、Amazon S3バケットに格納されているデータへのアクセスを有効にするために、S3_CREDという名前のストレージ資格証明をDatabricksに作成します。

-- S3 credential
BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('S3_CRED'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'S3_CRED',
    username        => '<aws_access_key_id>',
    password        => '<aws_secret_access_key>'
  );
END;
/

外部Iceberg表の作成

DatabricksにORDERS_GLUEという名前の外部Iceberg表を作成します。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'ORDERS_GLUE',
    credential_name => 'S3_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "aws_glue",
          "iceberg_glue_region": "us-east-1",
          "iceberg_table_path": ["<database>.<table>"]
        }
      }
    }'
  );
END;
/

クイック機能チェック

次のプロシージャは、外部表ORDERS_GLUEのすべての行をカウントする問合せを実行して、接続およびデータ・アクセシビリティを検証します。

SELECT COUNT(*) FROM ORDERS_GLUE;

Hadoop/ファイルシステム(ダイレクト・メタデータ・ファイル)

このトピックでは、ADLS、S3、OCIなどのオブジェクト・ストアから直接Iceberg表のメタデータ・ファイルにアクセスするためのストレージ資格証明を作成する方法について説明します。ここでは、カタログ・サービスを使用せずに、ファイル・システム(通常はHadoop互換ファイル・システム)に直接格納されているIceberg表の直接メタデータ管理のタイプの分類について説明します。

例: JSONメタデータを使用したIceberg表の問合せ

前提条件

表のIcebergルート・マニフェスト(metadata.json)には、オブジェクト・ストア(ADLS/S3/OCI)からアクセスできます。
このパスは point-in-timeです。新しいスナップショットをたどるには、外部表を再作成します。

ストレージ資格証明の作成

このプロシージャは、STORE_CREDという既存の資格証明が存在する場合は、まず削除しようとします(エラーは無視されます)。次に、STORE_CREDという名前の新しい資格証明を作成します。

-- Storage credential for wherever the metadata.json lives
BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('STORE_CRED'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'STORE_CRED',
    username        => '<user-or-key>',
    password        => '<secret-or-token>'
  );
END;
/

外部表の作成

これにより、CUSTOMERS_METAという名前の外部表が作成されます。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_META',
    credential_name => 'STORE_CRED',
    file_uri_list   => 'https://<bucket-or-container>/<path>/metadata.json',
    format          => '{"access_protocol":{"protocol_type":"iceberg"}}'
  );
END;
/

クイック機能チェック

次のプロシージャは、外部表のすべての行をカウントする問合せを実行します。

SELECT COUNT(*) FROM CUSTOMERS_META;

例: OCI上のHadoopカタログを使用したIceberg表の問合せ

この例では、OCIデータ・フローを使用して作成されたIceberg表db.icebergTablePyを問い合せます。この場合、SparkはIcebergカタログのHadoopCatalog実装を使用します。HadoopCatalogは、バケットmy-iceberg-bucketのlakehouseフォルダicebergを使用し、Icebergメタデータをこのディレクトリの下の$database_name/$table_nameサブフォルダに配置します。また、最新のメタデータ・ファイル・バージョンのバージョン番号を含むversion-hint.textファイルも使用します。

表db.icebergTablePyの外部表を次のように作成します。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       => 'iceberg_parquet_time_dim3',
    credential_name  => 'OCI_CRED',
    format           => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "hadoop",
          "iceberg_warehouse": "https://objectstorage.uk-cardiff-1.oraclecloud.com/n/my-tenancy/b/my-iceberg-bucket/o/iceberg",
          "iceberg_table_path": "db.icebergTablePy"
        }
      }
    }'
  );
END;
/

参照

このセクションでは、この章を通して引用されているリンクの参照先の一覧を示します。

DBMS_クラウド.CREATE_EXTERNAL_TABLE
DBMS_クラウド.作成_資格証明
Autonomous AI Database Insiderに関するブログ: Iceberg Tables: A New Data Source for Oracle Autonomous AI Database
[Apache IcebergとAutonomous AI Databaseによるレイクハウスの構築] javidatatech.com(https://www.javidatatech.com/building-lakehouses-with-apache-iceberg-and-autonomous-database/)

Oracle Cloud Infrastructureドキュメント

Apache Iceberg表の問合せ

Apache Iceberg表の問合せについて

サポートされる構成

デルタ・レイクUniForm表

Apache Iceberg表の問合せの制限事項

Apache Iceberg表の問合せに関連する概念

Icebergの設定要件

Icebergの資格証明: RESTカタログとオブジェクト・ストア

前提条件: Iceberg操作のためのネットワーク・アクセス制御リスト(ACL)の付与

Iceberg操作のスキーマ・ロールの付与

Apache Iceberg表の問合せの一般的なワークフロー

プロバイダのクイックスタート

Databricks Unityカタログ

スノーフレークポラリス

AWS Glueカタログ

Hadoop/ファイルシステム(ダイレクト・メタデータ・ファイル)

参照