表のオプションを構成する

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

Lakehouse ランタイム カタログのテーブル オプションを使用すると、Apache Iceberg テーブルで BigQuery DML 書き込みの相互運用性と自動テーブル管理（ストレージ最適化）を有効にできます。

Lakehouse ランタイム カタログでサポートされているテーブル形式とオプトイン機能の詳細については、テーブルタイプの比較と Apache Iceberg テーブルの概要をご覧ください。

始める前に

1. Google Cloud プロジェクトに対して課金が有効になっていることを確認します。

2. BigLake API を有効にします（有効になっていない場合）。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。

   API の有効化

3. Apache Iceberg REST カタログ エンドポイントを使用して Lakehouse ランタイム カタログを設定します。

必要なロール

テーブル オプションの構成に必要な権限を取得するには、プロジェクトとストレージ バケットに対する次の IAM ロールを付与するよう管理者に依頼してください。

• 認証情報自動販売モードでテーブル プロパティを構成する: BigLake 編集者（roles/biglake.editor）- プロジェクト
• 非認証情報提供モードでテーブル プロパティを構成します。
  • BigLake 編集者（roles/biglake.editor）- プロジェクト
  • Storage オブジェクト ユーザー（roles/storage.objectUser）- Cloud Storage バケット

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

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

構成に関する考慮事項

テーブル オプションを構成する際は、次の要件とデフォルトの動作を考慮してください。

サポートされている Iceberg テーブル

Apache Iceberg V2（一般提供）テーブルと V3（プレビュー）テーブルのみがサポートされています。Iceberg V1 テーブルはサポートされていません。既存の V1 テーブルをアップグレードするには、Iceberg V1 テーブルを V2 にアップグレードするをご覧ください。

認証情報ベンディングの要件

テーブルの自動管理を有効にするには、Lakehouse ランタイム カタログでカタログレベルで認証情報の払い出しを有効にする必要があります。テーブル管理のバックグラウンド ジョブは、認証情報提供サービス アカウントを使用して、基盤となるストレージ データファイルの認証と更新を行います。

BigQuery DML を有効にする

BigQuery データ操作言語（DML）ステートメントを有効にすると、オープンソース エンジンを使用して作成された Apache Iceberg テーブルで BigQuery からの書き込み相互運用性が有効になります。

サポートされているステートメントには、INSERT、UPDATE、DELETE、MERGE、CREATE TABLE、ALTER TABLE、DROP TABLE などの標準の DDL ステートメントが含まれます。ただし、BigQuery の Apache Iceberg テーブルでサポートされていないステートメントは除きます。

新しいテーブルで BigQuery DML を有効にする

BigQuery からテーブルを作成すると、BigQuery DML と自動テーブル管理がデフォルトで有効になります。オープンソース エンジンからテーブルを作成する場合は、エンジンの DDL 構文を使用して gcp.biglake.bigquery-dml.enabled = true テーブル プロパティを構成します。

たとえば、Spark SQL では次のようになります。

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

既存のテーブルで BigQuery DML を有効にする

既存のテーブルで BigQuery DML を有効にするには、テーブル プロパティを更新します。

たとえば、Spark SQL では次のようになります。

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

BigQuery DML を無効にする

BigQuery DML を無効にすると、テーブルは BigQuery に対して読み取り専用になり、自動テーブル管理が停止します。

たとえば、Spark SQL では次のようになります。

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

テーブル管理を有効にする

テーブル管理では、バックグラウンド プロセスを自動化して、ストレージを最適化し、圧縮やガベージ コレクションなどのデータとメタデータのライフサイクルを管理します。

テーブル管理では、次の操作を行うことができます。

• スナップショットの有効期限とガベージ コレクション: スナップショットの有効期限は、テーブル スナップショットからのデータファイルとメタデータ ファイルの保持と削除を管理します。これは、データの変更後にバックグラウンドで自動的に実行されます。スナップショットは、ユーザーが構成した Iceberg テーブルのプロパティ history.expire.max-snapshot-age-ms と history.expire.min-snapshots-to-keep に基づいて期限切れになります。期限切れのスナップショット エントリを削除するには、追加のスナップショット定義をもう 1 つ作成します。この定義は、削除されたスナップショットへの参照を含まない新しいメタデータ ファイルによってマニフェストされます。

  • 制限事項: テーブルでタグまたはブランチが使用されている場合、スナップショットの有効期限と関連するガベージ コレクションはスキップされます。詳細については、制限事項をご覧ください。

  • 制限事項: 孤立したファイルの削除は、自動テーブル管理では処理されません。詳細については、制限事項をご覧ください。

• Coalesce（圧縮）: Coalesce は、小さなファイルを大きなファイルにマージすることで、データの形状を維持します。Coalesce は、データ変更後にバックグラウンドで自動的に実行されます。圧縮対象として選択されるのは、非圧縮時の平均サイズがターゲット ファイル サイズ（256 MB）の 50% 未満のファイルです。各結合オペレーションにより、新しいテーブル スナップショットが生成されます。通常、Coalesce ジョブは、実行中の DML オペレーションの後に譲り、再試行します。ただし、ストレージ最適化の無期限の枯渇を防ぐため、データが結合の対象となる場合は、24 時間ごとに結合ジョブが強制的にトリガーされます。

• テーブル管理ジョブのモニタリング: すべてのバックグラウンド テーブル管理ジョブは、BigQuery の INFORMATION_SCHEMA.JOBS ビューに記録されます。このビューをクエリして、他の BigQuery ジョブをモニタリングする場合と同様に、これらのオペレーションを追跡できます。ジョブ情報のクエリの詳細については、Iceberg ストレージ最適化ジョブを取得するをご覧ください。

  テーブル管理ジョブの頻度は、データ変更アクティビティと直接相関しています。頻繁に小さな挿入や更新を行うと、バックグラウンド タスクがより頻繁にトリガーされます。テーブルへの書き込みがない場合、バックグラウンド ジョブがない期間が発生することがあります。逆に、書き込み量が多いと、INFORMATION_SCHEMA でジョブ アクティビティがより多く表示される可能性があります。

新しいテーブルのテーブル管理を有効にする

BigQuery からテーブルを作成すると、DML と自動テーブル管理がデフォルトで有効になります。オープンソース エンジンからテーブルを作成する場合は、gcp.biglake.table-management.enabled プロパティを構成します。テーブル管理を有効にすると、BigQuery DML がまだ有効になっていない場合は自動的に有効になります。

たとえば、Spark SQL では次のようになります。

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

既存のテーブルのテーブル管理を有効にする

既存のテーブルでテーブル管理を有効にするには、テーブル プロパティを更新します。

たとえば、Spark SQL では次のようになります。

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

テーブル管理を無効にする

テーブル管理を無効にすると、今後のバックグラウンド最適化ジョブがキューに追加されなくなります。ただし、アクティブな進行中のジョブは完了します。テーブル管理を無効にしても、BigQuery DML は無効になりません。

Spark SQL

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

制限事項

マネージド機能（BigQuery の書き込み相互運用性や自動テーブル管理など）の制限事項は次のとおりです。

一般的な制限事項

• マネージド機能は、Apache Iceberg REST カタログ エンドポイントを使用して Lakehouse ランタイム カタログに作成された Apache Iceberg テーブルでのみサポートされます。
• BigQuery で管理される Apache Iceberg テーブルの既存の制限はすべて、マネージド機能が有効になっているオペレーションに適用されます。
• Apache Iceberg format-version 3 のテーブルでは、マネージド機能はサポートされていません。マネージド機能にオプトインできるのは、フォーマット バージョン 2（Iceberg v2 仕様）のテーブルのみです。
• STRING によるパーティショニング、複数列のパーティショニング、パーティションの進化など、高度なパーティショニングを使用するテーブルでは、マネージド機能はサポートされていません。
• 並べ替え順序で構成されたテーブル（WRITE ORDER BY プロシージャの使用や write.distribution.mode = range の設定など）では、マネージド機能はサポートされていません。
• 読み取り時マージモードを使用する Iceberg v2 テーブルでは、マネージド機能はサポートされていません。コピーオンライトの更新、削除、マージモードを使用するテーブルのみが、マネージド機能にオプトインできます。
• マネージド機能は、gzip、lz4、brotli コーデック（write.parquet.compression.codec）を使用して圧縮されたデータファイルをサポートしていません。データファイルでサポートされている圧縮タイプは zstd と snappy のみです。
• スキーマに、構造内のネストされたパスまたはフィールドを参照するネストされた主キー識別子（identifier-field-ids）が含まれている場合、テーブルでマネージド機能はサポートされません。
• カスタムデータまたはメタデータのロケーション（write.data.path と write.metadata.path）を持つテーブルでは、マネージド機能はサポートされていません。データファイルとメタデータ ファイルを保持するには、デフォルトの Cloud Storage バケットのロケーションが必要です。
• Lakehouse ランタイム カタログで管理されている Apache Iceberg テーブルでは、BigQuery クラスタリングはサポートされていません。
• BigQuery で NUMERIC データ型を使用してテーブルが作成された場合、Spark は NUMERIC を NUMERIC(38,9) として読み取るため、Spark からのスキーマ更新は失敗します。回避策として、BigQuery で NUMERIC 型のテーブルを作成するときに、精度を NUMERIC(38,9) に明示的に設定します。
• 既知の問題: DDL（ALTER TABLE ... DROP COLUMN）を使用して BigQuery で列を削除した直後に、同じ名前の列を再追加することはサポートされていません。

タイムトラベルの制限事項

• テーブル管理が有効になっている場合、history.expire.max-snapshot-age-ms プロパティの推奨最大値は 7 日です。
• タイムトラベルの BigQuery プロジェクト レベルまたはデータセット レベルの構成は適用されません。Iceberg テーブルのプロパティとデフォルトのみが有効です。

テーブル管理の制限事項

• テーブルにタグまたはブランチを含むスナップショットが含まれている場合、テーブル全体のスナップショットの有効期限はスキップされます。ALTER... RETAIN x DAYS を使用して設定されたカスタム保持は無視され、history.expire.max-ref-age-ms プロパティに設定された値は無視されます。オープンソース エンジンは、引き続きスナップショットの有効期限を処理できます。
• 自動テーブル管理では、スキーマやパーティション仕様の有効期限は切れません。metadata.json ファイルには、スキーマ ID を参照するスナップショットがない場合でも、スキーマとパーティション仕様の完全な履歴が保持されます。

• BigQuery またはオープンソース エンジンによって作成された孤立したファイルは、自動テーブル管理によってクリーンアップされません。オープンソース エンジンは、孤立したファイルのクリーンアップを実行できます（たとえば、prefix_listing オプションを true に設定して Spark remove_orphan_files プロシージャを使用します）。

  警告: 孤立したファイルのクリーンアップを実行すると、クエリが older_than しきい値（デフォルトは 3 日）を超えて実行されている場合、アクティブな長時間実行クエリからファイルが削除される可能性があります。older_than パラメータは慎重に設定してください。

• Coalesce は、Z オーダーと線形並べ替えをサポートしていません。テーブルにこれらのプロパティが含まれている場合、coalesce の実行後にレイアウトが維持されるとは限りません。テーブルにこれらのプロパティが含まれている場合は、テーブル管理を有効にしないことをおすすめします。

パーティショニングの制限事項

• オープンソース エンジンからテーブルを作成または登録する場合、マネージド機能は、hour、day、month、year 変換（DATE フィールドの hour 変換を除く）を使用した DATE、DATETIME、TIMESTAMP フィールド タイプと、INTEGER フィールド タイプでのパーティショニングのみをサポートします。
• マネージド機能は、IDENTITY 変換を含むテーブルではサポートされていません。ユーザーは変換を明示的に指定する必要があります。
• マネージド機能を持つテーブルに対する CREATE OR REPLACE コマンドは、同じパーティション仕様を使用している場合にのみサポートされます。次の置換はサポートされていません。
  • パーティション分割されていないテーブルをパーティション分割テーブルに置き換える。
  • パーティション分割テーブルをパーティション分割されていないテーブルに置き換える。
  • パーティション分割テーブルを、別のパーティショニング仕様を使用するテーブルに置き換える。
• カスタム パーティション フィールドの命名はサポートされていません。オープンソース エンジンから作成または登録されたテーブルは、エンジンのデフォルトのパーティション フィールド命名規則（_ と変換名（_hour、_day、_month、_year など）を追加）に従う必要があります。たとえば、DAY 変換を使用する time_date という名前のフィールドの場合、想定されるパーティション フィールド値は json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform } です。

カスタム Iceberg テーブル プロパティの制限事項

マネージド機能が有効になっている場合、次のテーブル動作プロパティをデフォルト以外の値に構成することはできません。マネージド機能が有効になっている場合、デフォルト値はハードコードされます。

プロパティ	デフォルト値	詳細
format-version	2	マネージド機能は Iceberg v2 テーブルのみをサポートしています。
write.format.default	parquet	テーブルは Parquet 形式のデータファイルのみをサポートします。
write.data.path	table location + /data	Apache Iceberg REST カタログ エンドポイントに構成されているデフォルトの Cloud Storage バケットパスが、データファイルの書き込みに使用されます。
write.metadata.path	table location + /metadata	Apache Iceberg REST カタログ エンドポイントに構成されているデフォルトの Cloud Storage バケットパスが、メタデータ ファイルの書き込みに使用されます。
write.delete.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、コピーオンライトのみをサポートしています。
write.update.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、コピーオンライトのみをサポートしています。
write.merge.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、コピーオンライトのみをサポートしています。
write.delete.isolation-level	厳格な競合検出	metadata.json ファイルを変更する変更（データの競合、メタデータの競合、ファントム読み取り、競合しない同時書き込みなど）により、同時トランザクションが失敗し、再試行されます。
write.update.isolation-level	厳格な競合検出	write.delete.isolation-level と同じ動作。
write.merge.isolation-level	厳格な競合検出	write.delete.isolation-level と同じ動作。

オープンソース エンジンからテーブルを作成または変更するときに、次のプロパティを構成できます。

プロパティ	デフォルト値	詳細
write.parquet.compression-codec	zstd	BigQuery の書き込みとストレージの最適化では、zstd 圧縮形式と snappy 圧縮形式のみがサポートされています。他の圧縮形式（gzip、brotli、lz4 など）はサポートされていません。
write.metadata.compression-codec	null	null または gzip に構成できます。
history.expire.max-snapshot-age-ms	432000000（5 日）	任意の正の整数に構成できますが、テーブル管理が有効になっている場合は、最大 7 日間（604,800,000 ミリ秒）にすることをおすすめします。テーブル管理ジョブは、指定された期間より古いスナップショットを削除します。
history.expire.min-snapshots-to-keep	1	任意の正の整数に構成できます。テーブル管理ジョブは、少なくともこの数のスナップショットを保持します。

write.target-file-size-bytes や write.parquet.page-size-bytes などの他の Apache Iceberg 書き込みプロパティは、オープンソース エンジンから構成できますが、BigQuery の書き込みジョブとテーブル管理ジョブは、これらのプロパティに準拠していない可能性があります。

次のステップ

• BigQuery DML を使用してデータを変更する方法を学習する。
• テーブルをクエリする方法を学習する。