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 外部テーブルは別物です。Apache Iceberg 用の BigQuery テーブルのみが書き込み可能であるためです。Apache Iceberg 用の BigLake 外部テーブルは、Apache Spark など別のクエリエンジンから生成された読み取り専用テーブルで、BigQuery を使用してのみクエリできます。

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

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

アーキテクチャ

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

操作	結果	予防策
BigQuery の外部にあるバケットに新しいファイルを追加します。	データ損失: BigQuery の外部に追加された新しいファイルやオブジェクトは、BigQuery によって追跡されません。追跡されないファイルは、バックグラウンドのガベージコレクションプロセスによって削除されます。	データの追加を常に BigQuery を介して行うと、BigQuery によってファイルが追跡され、ガベージコレクションを防止できます。誤って追加されることやデータが失われることがないように、Iceberg テーブルを含むバケットに対して、外部ツールの書き込み権限を制限することもおすすめします。
空でない接頭辞に新しい Iceberg テーブルを作成します。	データ損失: 既存のデータは BigQuery によって追跡されないため、これらのファイルは追跡対象外とみなされ、バックグラウンドのガベージコレクションプロセスによって削除されます。	空の接頭辞にのみ新しい Iceberg テーブルを作成します。
Iceberg テーブルのデータファイルを変更または置換する	データ損失: 外部で変更または置換を行うと、テーブルの整合性チェックが失敗して読み取り不能になり、テーブルに対するクエリが失敗します。この状態からセルフサービスで復元する方法はありません。データ復元の支援のため、サポートにご連絡ください。	データの変更を常に BigQuery を介して行うと、BigQuery によってファイルが追跡され、ガベージコレクションを防止できます。誤って追加されることやデータが失われることがないように、Iceberg テーブルを含むバケットに対して、外部ツールの書き込み権限を制限することもおすすめします。
同じ、または重複している URI に Apache Iceberg 用の BigQuery テーブルを 2 つ作成する	データ損失: BigQuery は、Iceberg テーブルの同じ URI インスタンスをブリッジしません。各テーブルのバックグラウンドのガベージコレクションプロセスは、もう一方のテーブルにあるファイルを追跡対象外とみなして削除するため、データ損失が発生します。	Iceberg テーブルごとに一意の URI を使用します。

課金

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

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

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

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

必要な権限

BigQuery によるプロジェクト内のテーブルの管理を許可するには、次の権限が必要です。

プロジェクトに対する bigquery.connections.delegate。
プロジェクトに対する bigquery.jobs.create。
プロジェクトに対する bigquery.readsessions.create。
プロジェクトに対する bigquery.tables.create。
プロジェクトに対する bigquery.tables.get。
プロジェクトに対する bigquery.tables.getData。
プロジェクトに対する storage.buckets.get。
プロジェクトに対する storage.objects.create。
プロジェクトに対する storage.objects.delete。
プロジェクトに対する storage.objects.get。
プロジェクトに対する storage.objects.list。

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

Iceberg テーブルを作成する

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

SQL

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

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

PROJECT_NAME: データセットを含むプロジェクト。未定義の場合、コマンドはデフォルトのプロジェクトを想定します。
DATASET_NAME: 既存のデータセット。
TABLE_NAME: 作成するテーブルの名前。
DATA_TYPE: 列に含まれる情報のデータ型。
CLUSTER_COLUMN_LIST: 最大 4 つの列を含むカンマ区切りリスト。最上位の非繰り返し列である必要があります。
CONNECTION_NAME: 接続の名前。例: myproject.us.myconnection。
STORAGE_URI: 完全修飾の Cloud Storage URI。例: gs://mybucket/table。

bq

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

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

PROJECT_NAME: データセットを含むプロジェクト。未定義の場合、コマンドはデフォルトのプロジェクトを想定します。
CONNECTION_NAME: 接続の名前。例: myproject.us.myconnection。
STORAGE_URI: 完全修飾の Cloud Storage URI。例: gs://mybucket/table。
COLUMN_NAME: 列の名前。
DATA_TYPE: 列に含まれる情報のデータ型。
CLUSTER_COLUMN_LIST: 最大 4 つの列を含むカンマ区切りリスト。最上位の非繰り返し列である必要があります。
MANAGED_TABLE_NAME: 作成するテーブルの名前。

API

次のように、定義済みのテーブルリソースを使用して tables.insert メソッドを呼び出します。

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

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

TABLE_NAME: 作成するテーブルの名前。
CONNECTION_NAME: 接続の名前。例: myproject.us.myconnection。
STORAGE_URI: 完全修飾の Cloud Storage URI。ワイルドカードもサポートされます。例: gs://mybucket/table。
COLUMN_NAME: 列の名前。
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 テーブルが作成されます。

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

SQL

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

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

MANAGED_TABLE_NAME: 既存の Iceberg テーブルの名前。
STORAGE_URI: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードもサポートされます。例: gs://mybucket/table。
FILE_FORMAT: ソーステーブルの形式。サポートされている形式については、load_option_list の format 行をご覧ください。

bq

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

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

FILE_FORMAT: ソーステーブルの形式。サポートされている形式については、load_option_list の format 行をご覧ください。
MANAGED_TABLE_NAME: 既存の Iceberg テーブルの名前。
STORAGE_URI: 完全修飾の Cloud Storage URI または URI のカンマ区切りのリスト。ワイルドカードもサポートされます。例: gs://mybucket/table。

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

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

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

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

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

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

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

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

メタデータを Iceberg テーブルとしてエクスポートする

Iceberg テーブルのメタデータを Iceberg テーブルとしてエクスポートするには、次のいずれかの方法を選択します。

bq

EXPORT TABLE METADATA ステートメントを使用します。

次の例では、テーブルのメタデータを Iceberg 形式でテーブルの storage_uri の metadata フォルダにエクスポートします。

bq query \
  --nouse_legacy_sql \
  --nouse_cache "EXPORT TABLE METADATA FROM TABLE_NAME"

Spark

Apache Spark では、HadoopCatalog を使用してテーブルメタデータをエクスポートできます。

次のサンプルでは、Apache Iceberg で Spark SQL が使用されるように環境を設定し、Iceberg テーブルを管理するカタログを確立してから、クエリを実行して指定された 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 テーブルを変更するには、テーブルスキーマの変更の手順に沿って操作します。

料金

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

Apache Iceberg 用の BigQuery テーブル

アーキテクチャ

ベスト プラクティス

課金

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

始める前に

必要なロール

必要な権限

Iceberg テーブルを作成する

SQL

bq

API

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

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

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

SQL

bq

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

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

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

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

メタデータを Iceberg テーブルとしてエクスポートする

bq

Spark

Iceberg テーブルを変更する

料金

ストレージ

ストレージ最適化

クエリとジョブ

制限事項

ベストプラクティス

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

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