Apache Iceberg 用の BigQuery テーブル

プレビュー版のサポートについては、bigquery-tables-for-apache-iceberg-help@google.com までメールでお問い合わせください。

Apache Iceberg 用の BigQuery テーブル（以下、Iceberg テーブル）は、 Google Cloudでオープン形式のレイクハウスを構築するための基盤になります。Iceberg テーブルは BigQuery テーブルと同じフルマネージド エクスペリエンスを提供します。また、Parquet を使用してお客様所有のストレージ バケットにデータを保存することで、オープン形式の Iceberg テーブル形式と相互運用が可能です。

Apache Iceberg 用の BigQuery テーブルと、Apache Iceberg 用の BigLake 外部テーブルは別物で、BigQuery 内で直接変更できるのは Apache Iceberg 用の BigQuery テーブルのみです。Apache Iceberg 用の BigLake 外部テーブルは、Apache Spark など別のクエリエンジンから生成された読み取り専用テーブルで、BigQuery を使用してのみクエリできます。

Iceberg テーブルは、次の機能をサポートしています。

• テーブル ミューテーション: GoogleSQL データ操作言語（DML）を使用します。
• 統合されたバッチ処理と高スループット ストリーミング: Spark、Dataflow、その他のエンジンなどの BigLake コネクタを介して Storage Write API を使用します。
• スキーマの進化: ニーズに合わせて列の追加、削除、名前の変更を行えます。この機能を使用すると、既存の列のデータ型の変更や、列モードの変更ができます。詳細については、型変換規則をご覧ください。
• ストレージの自動最適化: 適応型ファイルサイズ設定、自動クラスタリング、ガベージ コレクション、メタデータの最適化などが含まれます。
• 列レベルのセキュリティとデータ マスキング。

次の表に、BigQuery Iceberg テーブルと BigQuery の他の類似テーブルの種類を比較します。

アーキテクチャ

Iceberg テーブルを使用すると、独自のクラウド バケットに存在するテーブルで、BigQuery リソース管理の利便性を享受できます。Iceberg テーブルにより、管理するバケットからデータを移動することなく、これらのテーブルで BigQuery を使用できます。

次の図は、マネージド テーブルのアーキテクチャの概要を示しています。

このテーブル管理は、バケットに次のような影響を与えます。

• BigQuery は、書き込みリクエストやバックグラウンドのストレージ最適化（DML ステートメントやストリーミングなど）に応じて、バケットに新しいデータファイルを作成します。
• BigQuery でマネージド テーブルを削除しても、関連するデータファイルは削除されません。確実に削除するには、ファイルと、エクスポートされたテーブル メタデータを、バケットから手動で削除する必要があります。
• Iceberg テーブルを使用するうえで、BigQuery のストレージ費用は発生しません。詳しくは、お支払いをご覧ください。

Iceberg テーブルの作成は、BigQuery テーブルの作成と似ています。データをオープン形式で Cloud Storage に保存するため、以下のようなオプションも使用できます。

• WITH CONNECTION を使用して Cloud リソース接続を指定し、BigLake が Cloud Storage にアクセスするための接続認証情報を構成します。
• file_format を使用してデータ ストレージのファイル形式を指定します。PARQUET はプレビュー版でサポートされています。
• table_format を使用してオープンソースのメタデータ テーブル形式を指定します。ICEBERG はプレビュー版でサポートされています。

ベスト プラクティス

BigQuery の外部でバケットのファイルを直接変更または追加すると、データ損失や回復不能エラーが発生する可能性があります。次の表に、考えられるシナリオを示します。

ロケーションに関する考慮事項

マルチリージョン バケットではなく、Cloud Storage のシングル リージョン バケットまたはデュアル リージョン バケットを使用することでパフォーマンスを改善できます。

課金

次の機能には、既存の公開済み料金で課金されます。

• Cloud Storage の料金。Cloud Storage バケットに保存されているデータ、Cloud Storage によるデータ処理、ご使用中のバケットから読み取られたデータ量に対するネットワーク使用量がすべて含まれます。
• BigQuery コンピューティングの料金。クエリ、DML、バックグラウンド ストレージ最適化（クラスタリング、統合、ガベージ コレクションなど）で発生します。
  • 予約（スロット）の使用料は、既存のスロット料金に従います。
  • オンデマンドの最小管理単位（SKU）を使用する料金は、既存のオンデマンド料金に従います。詳細については、BigLake の費用をご覧ください。
• バッチ読み込みと抽出のコンピューティングは、オンデマンド SKU または予約（スロット）を使用して課金されます。
• Storage Read API の料金: Read API を介した Spark からの読み取り。
• Storage Write API の料金: ストリーミング。

Iceberg テーブルのワークフロー

次のセクションでは、マネージド テーブルの作成、読み込み、管理、クエリの方法について説明します。

始める前に

Iceberg テーブルを作成して使用する前に、ストレージ バケットへの Cloud リソース接続が設定されていることを確認してください。次の必要なロール セクションで指定されているように、接続にはストレージ バケットへの書き込み権限が必要です。接続に必要なロールと権限の詳細については、接続を管理するをご覧ください。

必要なロール

プロジェクト内のテーブルを BigQuery が管理できるようにするために必要な権限を取得するには、次の IAM ロールの付与を管理者に依頼してください。

• Iceberg テーブルを作成するには:
  • プロジェクトに対する BigQuery データオーナー（roles/bigquery.dataOwner）
  • プロジェクトに対する BigQuery Connection 管理者（roles/bigquery.connectionAdmin）
• Iceberg テーブルをクエリするには:
  • プロジェクトに対する BigQuery データ閲覧者（roles/bigquery.dataViewer）
  • プロジェクトに対する BigQuery ユーザー（roles/bigquery.user）
• Cloud Storage でのデータの読み取りと書き込みを接続サービス アカウントで行う場合:
  • バケットに対するストレージ オブジェクト ユーザー（roles/storage.objectUser）
  • バケットに対する Storage レガシー バケット読み取り（roles/storage.legacyBucketReader）

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

これらの事前定義ロールには、プロジェクト内のテーブルの BigQuery による管理を許可するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

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

Iceberg テーブルを作成する

Iceberg テーブルを作成するには、次のいずれかの方法を選択します。

CREATE TABLE [PROJECT_NAME.]DATASET_NAME.TABLE_NAME (
COLUMN DATA_TYPE[, ...]
)
CLUSTER BY CLUSTER_COLUMN_LIST
WITH CONNECTION {CONNECTION_NAME | DEFAULT}
OPTIONS (
file_format = 'PARQUET',
table_format = 'ICEBERG',
storage_uri = 'STORAGE_URI');

bq --project_id=PROJECT_NAME mk \
    --file_format=PARQUET \
    --table_format=ICEBERG \
    --connection_id=CONNECTION_NAME \
    --storage_uri=STORAGE_URI \
    --schema=COLUMN_NAME:DATA_TYPE[, ...] \
    --clustering_fields=CLUSTER_COLUMN_LIST \
    MANAGED_TABLE_NAME

{
"tableReference": {
  "tableId": "TABLE_NAME"
},
"biglakeConfiguration": {
  "connectionId": "CONNECTION_NAME",
  "fileFormat": "PARQUET",
  "tableFormat": "ICEBERG",
  "storageUri": "STORAGE_URI"
},
"schema": {
  "fields": [
    {
      "name": "COLUMN_NAME",
      "type": "DATA_TYPE"
    }
    [, ...]
  ]
}
}

Iceberg テーブルにデータをインポートする

次のセクションでは、さまざまなテーブル形式から Iceberg テーブルにデータをインポートする方法について説明します。

フラット ファイルからのデータの標準読み込み

Iceberg テーブルは、BigQuery 読み込みジョブを使用して外部ファイルを Iceberg テーブルに読み込みます。既存の Iceberg テーブルがある場合は、bq load CLI ガイドまたは LOAD SQL ガイドに沿って外部データを読み込みます。データの読み込み後、新しい Parquet ファイルが STORAGE_URI/data フォルダに書き込まれます。

既存の Iceberg テーブルがない場合に前述の手順を行うと、代わりに BigQuery テーブルが作成されます。

マネージド テーブルへのバッチ読み込みの、ツール固有の例については、以下をご覧ください。

LOAD DATA INTO MANAGED_TABLE_NAME
FROM FILES (
uris=['STORAGE_URI'],
format='FILE_FORMAT');

bq load \
  --source_format=FILE_FORMAT \
  MANAGED_TABLE \
  STORAGE_URI

Hive パーティション分割ファイルからの標準読み込み

BigQuery の標準読み込みジョブを使用して、Hive パーティション分割ファイルを Iceberg テーブルに読み込むことができます。詳細については、外部パーティション分割データの読み込みをご覧ください。

Pub/Sub からストリーミング データを読み込む

Pub/Sub BigQuery サブスクリプションを使用して、ストリーミング データを Iceberg テーブルに読み込むことができます。

Iceberg テーブルからデータをエクスポートする

次のセクションでは、Iceberg テーブルからさまざまなテーブル形式にデータをエクスポートする方法について説明します。

データをフラット形式にエクスポートする

Iceberg テーブルをフラット形式にエクスポートするには、EXPORT DATA ステートメントを使用してエクスポート先の形式を選択します。詳細については、データのエクスポートをご覧ください。

Iceberg テーブルのメタデータ スナップショットを作成する

Iceberg テーブルのメタデータ スナップショットを作成する手順は次のとおりです。

1. EXPORT TABLE METADATA SQL ステートメントを使用して、メタデータを Iceberg 形式にエクスポートします。

2. 省略可: Iceberg メタデータ スナップショットの更新をスケジュールします。設定された時間間隔で Iceberg メタデータ スナップショットを更新するには、スケジュールされたクエリを使用します。

次の例では、DDL ステートメント EXPORT TABLE METADATA FROM mydataset.test を使用して、My Scheduled Snapshot Refresh Query という名前のスケジュールされたクエリを作成します。コピー先データセットは mydataset です。DDL ステートメントは 24 時間ごとに実行されます。

bq query \
    --use_legacy_sql=false \
    --destination_dataset=mydataset
    --display_name='My Scheduled Snapshot Refresh Query' \
    --schedule='every 24 hours' \
    'EXPORT TABLE METADATA FROM mydataset.test'

Iceberg テーブルのメタデータ スナップショットを表示する

Iceberg テーブルのメタデータ スナップショットを更新すると、Iceberg テーブルが最初に作成された Cloud Storage URI でスナップショットを確認できます。/data フォルダには Parquet ファイルのデータシャードが含まれ、/metadata フォルダには Iceberg テーブルのメタデータ スナップショットが含まれます。

SELECT
  table_name,
  REGEXP_EXTRACT(ddl, r"storage_uri\s*=\s*\"([^\"]+)\"") AS storage_uri
FROM
  `mydataset`.INFORMATION_SCHEMA.TABLES;

mydataset と table_name は、実際のデータセットとテーブルのプレースホルダです。

Apache Spark で Iceberg テーブルを読み取る

HadoopCatalog を使用して Apache Spark でテーブルデータをセットアップし、読み取ります。

次の例では、Apache Iceberg で Spark SQL を使用するように環境をセットアップしてから、クエリを実行して、指定された Iceberg テーブルからデータを取得します。

spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-ICEBERG_VERSION_NUMBER \
  --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.CATALOG_NAME.type=hadoop \
  --conf spark.sql.catalog.CATALOG_NAME.warehouse='BUCKET_PATH' \

# Query the table
SELECT * FROM CATALOG_NAME.FOLDER_NAME;

次のように置き換えます。

• ICEBERG_VERSION_NUMBER: Apache Spark Iceberg ランタイムの現在のバージョン。Spark のリリースから最新バージョンをダウンロードしてください。
• CATALOG_NAME: Iceberg テーブルを参照するカタログ。
• BUCKET_PATH: テーブル ファイルを含むバケットへのパス。例: gs://mybucket/。
• FOLDER_NAME: テーブル ファイルを含むフォルダ。例: myfolder。

Iceberg テーブルを変更する

Iceberg テーブルを変更するには、テーブル スキーマの変更の手順に沿って操作します。

料金

Iceberg テーブルの料金には、次の 3 つの部分が含まれています。

ストレージ

Iceberg テーブルは、すべてのデータを Cloud Storage に保存します。保存されたすべてのデータ（過去のテーブルデータを含む）に対して課金されます。必要に応じて、Cloud Storage のデータ処理と転送料金も適用される場合があります。BigQuery 固有のストレージ料金はありません。詳しくは、Cloud Storage の料金をご覧ください。

ストレージ最適化

Iceberg テーブルには、ファイルの統合や再クラスタリングなどのストレージ最適化オペレーションが必要です。これらの最適化オペレーションは、Enterprise エディションの従量課金制スロットを使用し、既存の BACKGROUND 予約は使用しません。

BigQuery Storage Write API を介してストリーミング中に実行されるデータのエクスポート オペレーションは Storage Write API の料金に含まれており、バックグラウンドでの保守としては課金されません。詳細については、データの取り込みの料金をご覧ください。

ストレージ最適化の使用状況は、[INFORMATION_SCHEMA.JOBS] ビューに表示されます。

クエリとジョブ

BigQuery テーブルと同様に、BigQuery オンデマンド料金を使用する場合はクエリと読み取りバイト数（TiB 単位）、BigQuery 容量コンピューティングの料金を使用する場合はスロットの使用量（スロット時間単位）に基づいて課金されます。

BigQuery の料金は、BigQuery Storage Read API と BigQuery Storage Write API にも適用されます。

読み込みオペレーションとエクスポート オペレーション（EXPORT METADATA など）は、Enterprise エディションの従量課金制スロットを使用します。これは、これらのオペレーションに対して料金が発生しない BigQuery テーブルと異なる点です。Enterprise または Enterprise Plus のスロットによる PIPELINE 予約が使用可能な場合、読み込みオペレーションとエクスポート オペレーションでは、代わりにこれらの予約スロットが優先的に使用されます。

制限事項

Iceberg テーブルには次の制限があります。

• Iceberg テーブルは、名前変更オペレーションや ALTER TABLE RENAME TO ステートメントをサポートしていません。
• Iceberg テーブルは、テーブルのコピーや CREATE TABLE COPY ステートメントをサポートしていません。
• Iceberg テーブルは、テーブル クローンや CREATE TABLE CLONE ステートメントをサポートしていません。
• Iceberg テーブルは、テーブル スナップショットや CREATE SNAPSHOT TABLE ステートメントをサポートしていません。
• Iceberg テーブルは、次のテーブル スキーマをサポートしていません。
  • 空のスキーマ
  • INTERVAL、JSON、RANGE、GEOGRAPHY のデータ型のスキーマ。
  • フィールドの照合順序を含むスキーマ。
  • デフォルト値の式を含むスキーマ。
• EXPORT METADATA は、精度が 38 桁を超える BIGNUMERIC または NUMERIC データ型を含むテーブルをサポートしていません。
• Iceberg テーブルは、次のスキーマ進化ケースをサポートしていません。
  • NUMERIC から FLOAT への型強制変換
  • INT から FLOAT への型強制変換
  • SQL DDL ステートメントを使用した、新しいネストされたフィールドの既存の RECORD 列への追加
• Iceberg テーブルでは、コンソールまたは API でクエリが実行されると、ストレージ サイズが 0 バイトと表示されます。
• Iceberg テーブルはマテリアライズド ビューをサポートしていません。
• Iceberg テーブルは、マルチステートメント トランザクションをサポートしていません。
• Iceberg テーブルは、変更データ キャプチャ（CDC）の更新をサポートしていません。
• Iceberg テーブルは、マネージド障害復旧をサポートしていません。
• Iceberg テーブルはパーティショニングをサポートしていません。代わりにクラスタリングを検討してください。
• Iceberg テーブルは、行レベルのセキュリティをサポートしていません。
• Iceberg テーブルはタイムトラベルをサポートしていません。
• Iceberg テーブルは、フェイルセーフ期間をサポートしていません。
• Iceberg テーブルは抽出ジョブをサポートしていません。
• INFORMATION_SCHEMA.TABLE_STORAGE ビューには、Iceberg テーブルは含まれません。
• Iceberg テーブルは、クエリ結果の宛先としてサポートされていません。
  • 代わりに、CREATE TABLE ステートメントを使用し、AS query_statement 引数を指定して、クエリ結果の宛先としてテーブルを作成することができます。
• CREATE OR REPLACE は、標準テーブルの Iceberg テーブルへの置き換え、または Iceberg テーブルの標準テーブルへの置き換えをサポートしていません。
• バッチ読み込みと LOAD DATA ステートメントは、既存の Iceberg テーブルへのデータの追加のみをサポートします。
• バッチ読み込みと LOAD DATA ステートメントは、スキーマの更新をサポートしていません。
• TRUNCATE TABLE は Iceberg テーブルをサポートしていません。これに代わる方法が 2 つあります。
  • CREATE OR REPLACE TABLE（同じテーブル作成オプションを使用）。
  • WHERE 句 true での DELETE FROM テーブル
• APPENDS テーブル値関数（TVF）は Iceberg テーブルをサポートしていません。
• Apache Spark における Iceberg のエクスポートでは、書き込みが最適化されたストレージに最近ストリーミングされたデータは含まれません。
• tabledata.list を使用したレコードベースのページ分割アクセスは、Iceberg テーブルをサポートしていません。
• Iceberg テーブルはリンク済みデータセットをサポートしていません。