Apache Iceberg 用の BigQuery テーブル

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

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

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

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

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

アーキテクチャ

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 の料金。
• クエリ、DML、バックグラウンド ストレージの最適化（クラスタリング、統合、ガベージ コレクションなど）の BigQuery コンピューティングの料金。
  • 予約（スロット）を使用した料金は、既存のスロット料金に従います。
  • オンデマンドの在庫管理単位（SKU）を使用する料金は、既存のオンデマンド料金に準じます。詳細については、BigLake の費用をご覧ください。
• バッチ読み込みと抽出のコンピューティングは、オンデマンド SKU または予約（スロット）を使用して課金されます。
• Read API を介して Spark から読み取る場合の Storage Read API の料金。
• ストリーミングの Storage Write API の料金。

Iceberg テーブル ワークフロー

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

始める前に

Iceberg テーブルを作成して使用する前に、ストレージ バケットへのクラウド リソース接続が設定されていることを確認します。接続には、次の必要なロールで指定されているように、ストレージ バケットに対する書き込み権限が必要です。

必要なロール

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.objectAdmin）
  • バケットに対するストレージのレガシー バケット読み取り （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
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 テーブルにデータをインポートする方法について説明します。

Parquet ファイルからの高速読み込み

copy_files_only オプションを使用すると、コンテンツを読み取って新しいファイルとして書き換えるのではなく、既存の Parquet ファイルをコピーすることで、データをより速く読み込むことができます。高速読み込みでは、通常のファイル読み込みに比べてコンピューティング容量が少なくなります。Parquet ファイルは Apache Iceberg 仕様と互換性があり、完全な列統計情報が必要です。高速読み込みでは、ファイルが読み取られて再処理されないため、ファイル内の無効な値（範囲外のタイムスタンプなど）は検出されません。Parquet ファイルの読み込みの詳細については、Parquet データの新しいテーブルへの読み込みをご覧ください。

フラットな Parquet ファイルを既存の Iceberg テーブルに高速に読み込むには、bq load コマンドを使用します。

bq load \
    --copy_files_only \
    --source_format=PARQUET \
    DATASET_NAME.TABLE_NAME \
    PATH_TO_SOURCE

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

• DATASET_NAME: Iceberg テーブルを含むデータセット。
• TABLE_NAME: データの読み込み先の Iceberg テーブルの名前。
• PATH_TO_SOURCE: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードもサポートされています。例: gs://mybucket/mydata*.parquet

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

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 テーブルを読み取る

Iceberg 形式の Iceberg テーブルからデータを読み取る手順は次のとおりです。

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

2. 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' \
   
   # Queries the table
   spark-sql> 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 テーブルを変更するには、テーブル スキーマの変更の手順に沿って操作します。

料金

アイスバーグ テーブルの料金は、次の 3 つのコンポーネントで構成されます。

ストレージ

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

ストレージ最適化

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

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

クエリとジョブ

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）の更新をサポートしていません。
• BigQuery Storage Write API を使用して Iceberg テーブルにデータをストリーミングする場合は、まずクエリキャッシュを無効にする必要があります。
• Iceberg テーブルはマネージド障害復旧をサポートしていません。
• Iceberg テーブルはパーティショニングをサポートしていません。代わりにクラスタリングを検討してください。
• Iceberg テーブルは、行レベルのセキュリティをサポートしていません。
• Iceberg テーブルはタイムトラベルをサポートしていません。
• Iceberg テーブルはフェイルセーフ ウィンドウをサポートしていません。
• Iceberg テーブルは抽出ジョブをサポートしていません。
• INFORMATION_SCHEMA.TABLE_STORAGE ビューには Iceberg テーブルは含まれません。
• Iceberg テーブルは、クエリ結果の宛先としてサポートされていません。
• CREATE OR REPLACE は、標準テーブルを Iceberg テーブルに置き換えることや、Iceberg テーブルを標準テーブルに置き換えることをサポートしていません。
• バッチ読み込みと LOAD DATA ステートメントは、既存の Iceberg テーブルへのデータの追加のみをサポートします。
• バッチ読み込みと LOAD DATA ステートメントは、スキーマの更新をサポートしていません。
• TRUNCATE TABLE は Iceberg テーブルをサポートしていません。次の 2 つの方法があります。
  • CREATE OR REPLACE TABLE（同じテーブル作成オプションを使用）。
  • DELETE FROM テーブル WHERE true
• APPENDS テーブル値関数（TVF）は Iceberg テーブルをサポートしていません。
• Apache Spark の Iceberg エクスポートには、書き込みが最適化されたストレージに最近ストリーミングされたデータは含まれません。
• 高速読み込みでは、柔軟な列名のファイルはサポートされていません。