Apache Iceberg 外部テーブルを作成する

Apache Iceberg 外部テーブルを使用すると、きめ細かいアクセス制御で読み取り専用形式の Apache Iceberg テーブルにアクセスできます。この機能は、BigQuery に書き込み可能な形式で Iceberg テーブルを作成できる BigQuery の Apache Iceberg 用 BigLake テーブルとは対照的です。

Iceberg は、ペタバイト規模のデータテーブルをサポートするオープンソースのテーブル形式です。Iceberg はオープンな仕様であるので、オブジェクト ストアに保存されたデータに対して複数のクエリエンジンを実行できます。Apache Iceberg 外部テーブル（以降、Iceberg 外部テーブルと呼びます）は、読み取り時のマージなど、Iceberg 仕様バージョン 2 をサポートしています。

BigQuery 管理者は、テーブルのデータ マスキングなど、行レベルと列レベルのアクセス制御を適用できます。テーブルレベルでアクセス制御を設定する方法については、アクセス制御ポリシーを設定するをご覧ください。Dataproc とサーバーレス Spark でテーブルのデータソースとして BigQuery Storage API を使用する場合も、テーブル アクセス ポリシーが適用されます。

Iceberg 外部テーブルは次の方法で作成できます。

• BigLake metastore を使用する（ Google Cloudの場合に推奨）。BigLake metastore は BigQuery カタログに基づいており、BigQuery と直接連携できます。BigLake metastore テーブルは複数のオープンソース エンジンから変更可能で、同じテーブルを BigQuery からクエリできます。BigLake metastore は、Apache Spark との直接統合もサポートしています。BigLake metastore を使用する Iceberg 外部テーブルは、BigLake Iceberg テーブルと呼ばれることもあります。

• AWS Glue Data Catalog を使用する（AWS の場合に推奨）。AWS Glue は、さまざまな AWS サービスに保存されているデータの構造と場所を定義し、自動スキーマ検出や AWS 分析ツールとの統合などの機能を提供する、一元化されたメタデータ リポジトリです。AWS では AWS Glue を使用することをおすすめします。

• Iceberg JSON メタデータ ファイルを使用する（Azure の場合に推奨）。Iceberg JSON メタデータ ファイルを使用する場合は、テーブルが更新されるたびに最新のメタデータ ファイルを手動で更新する必要があります。Apache Spark 用の BigQuery ストアド プロシージャを使用して、Iceberg メタデータ ファイルを参照する Iceberg 外部テーブルを作成できます。

制限事項の一覧については、制限事項をご覧ください。

始める前に

• Enable the BigQuery Connection and BigQuery Reservation APIs.

  Enable the APIs

• BigQuery で Spark のストアド プロシージャを使用して Iceberg 外部テーブルを作成する場合は、次の操作を行う必要があります。

  1. Spark 接続を作成します。
  2. その接続のアクセス制御を設定します。

• Iceberg 外部テーブル メタデータとデータファイルを Cloud Storage に保存するために、Cloud Storage バケットを作成します。メタデータ ファイルにアクセスするには、Cloud Storage バケットに接続する必要があります。方法は次のとおりです。

  1. Cloud リソースの接続を作成します。
  2. その接続にアクセス権を設定します。

必要なロール

Iceberg 外部テーブルの作成に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するように管理者へ依頼してください。

• BigQuery 管理者（roles/bigquery.admin）
• Storage オブジェクト管理者（roles/storage.objectAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、Iceberg 外部テーブルの作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

BigLake metastore を使用してテーブルを作成する

Iceberg 外部テーブルは、BigLake metastore を使って作成することをおすすめします。Apache Spark を使用して、これらのテーブルを作成できます。これを簡単に行うには、BigQuery ストアド プロシージャを使用します。例については、ストアド プロシージャを作成して実行するをご覧ください。

メタデータ ファイルを使用してテーブルを作成する

Iceberg 外部テーブルは、JSON メタデータ ファイルを使用して作成できます。ただし、Iceberg 外部テーブルを最新の状態に保つには、手動で JSON メタデータ ファイルの URI を更新する必要があるため、この方法はおすすめしません。URI が最新の状態でないと、BigQuery のクエリが失敗するか、Iceberg カタログを直接使用するその他のクエリエンジンと異なる結果になる可能性があります。

Iceberg テーブルのメタデータ ファイルは、Spark を使用して Iceberg テーブルを作成したときに指定した Cloud Storage バケットに作成されます。

次のオプションのいずれかを選択します。

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

テーブル メタデータの更新

JSON メタデータ ファイルを使用して Iceberg 外部テーブルを作成する場合は、テーブル定義を最新のテーブル メタデータに更新します。スキーマまたはメタデータ ファイルを更新するには、次のいずれかのオプションを選択します。

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

アクセス制御ポリシーを設定する

Iceberg 外部テーブルへのアクセスは、列レベルのセキュリティ、行レベルのセキュリティ、データ マスキングを使用して制御できます。

Iceberg 外部テーブルをクエリする

詳細については、Iceberg データにクエリを実行するをご覧ください。

データ マッピング

BigQuery は、次の表に示すように Iceberg のデータ型を BigQuery のデータ型に変換します。

制限事項

Iceberg 外部テーブルには、外部テーブルの制限事項と次の制限事項があります。

• Merge-on-Read を使用するテーブルには次の制限があります。

  • 各データファイルには最大 10,000 個の削除ファイルを関連付けることができます。
  • 削除ファイルに適用できる等価 ID は 100,000 個までです。
  • これらの制限を回避するには、削除ファイルを頻繁に圧縮するか、頻繁に変更されるパーティションを回避する Iceberg テーブルの上にビューを作成します。

• BigQuery では、Bucket を除くすべての Iceberg パーティション変換関数を使用したマニフェスト プルーニングがサポートされています。パーティションをプルーニングする方法については、パーティション分割テーブルに対してクエリを実行するをご覧ください。Iceberg 外部テーブルを参照するクエリでは、パーティション分割される列に対するリテラルが熟語に含まれている必要があります。

• Apache Parquet データファイルのみがサポートされています。

Merge-on-Read の費用

Merge-on-Read データのオンデマンド課金は、次のデータのスキャンの合計です。

• データファイルで読み取られたすべての論理バイト（位置削除と等価削除による削除としてマークされた行を含む）。
• 等価削除ファイルと位置削除ファイルを読み込んで、データファイル内の削除済み行を見つけるために読み取られた論理バイト数。

パーティション フィルタを要求

Iceberg テーブルのパーティション フィルタを要求するオプションを有効にすると、述語フィルタの使用を要求できます。このオプションが有効になっているときに、各マニフェスト ファイルに対応する WHERE 句を指定せずにテーブルにクエリを実行しようとすると、次のエラーが発生します。

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

各マニフェスト ファイルには、パーティションの除去に適した述語が少なくとも 1 つ必要です。

Iceberg テーブルの作成時に、次の方法で require_partition_filter を有効にできます。

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Iceberg テーブルを更新して、パーティション フィルタの要求を有効にすることもできます。

パーティション分割テーブルを作成するときに、パーティション フィルタを要求するオプションを有効にしない場合でも、テーブルを更新してオプションを追加できます。

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

次のステップ

• Spark のストアド プロシージャについて学習する。
• アクセス制御ポリシーについて学習する。
• BigQuery でのクエリの実行について確認する。
• BigQuery でサポートされているステートメントと SQL 言語について学習する。