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

プレビュー

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

テーブル オプションを構成すると、Lakehouse ランタイム カタログの Apache Iceberg テーブルで BigQuery の書き込み相互運用性またはテーブル管理（自動ストレージ最適化）を有効にできます。これらのオプションは、テーブルに対するオペレーションの機能を拡張する基本的な設定として機能します。

特定のテーブル プロパティを構成することで、BigQuery DML との書き込みの相互運用性を有効にしたり、テーブルの自動管理（ストレージの最適化）を有効にしたりできます。

Lakehouse ランタイム カタログでテーブルを使用する場合は、さまざまなテーブル タイプとそのオプトイン機能を理解すると便利です。Apache Iceberg テーブルの使用について詳しくは、Apache Iceberg テーブルの概要をご覧ください。

始める前に

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

2. BigLake API を有効にします。

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

   API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

   API の有効化

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

必要なロール

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

• 認証情報ベンディング モードでテーブル プロパティを構成する: BigLake 編集者（roles/biglake.editor） - プロジェクト
• 認証情報なしのベンディング モードでテーブルのプロパティを構成します。
  • BigLake 編集者（roles/biglake.editor）- プロジェクト
  • ストレージ オブジェクト ユーザー（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 に基づいて期限切れになります。期限切れのスナップショット エントリを metadata.json ファイルから削除し、期限切れのスナップショットにのみ属し、ライブ スナップショットから参照されなくなったデータファイルとメタデータ ファイルを物理的に削除します。

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

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

• 統合（圧縮）: 統合は、小さなファイルを大きなファイルにマージすることで、データの形状を維持します。Coalesce は、データ変更後にバックグラウンドで自動的に実行されます。ファイルの非圧縮サイズの平均が、ターゲット ファイルサイズ（256 MB）の 50% 未満の場合、ファイルは圧縮用に選択されます。統合オペレーションごとに、新しいテーブル スナップショットが生成されます。通常、統合ジョブは実行中の 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 カタログ エンドポイントを使用してレイクハウス ランタイム カタログに作成された Apache Iceberg テーブルでのみサポートされます。
• BigQuery で管理される Apache Iceberg テーブルの既存の制限はすべて、マネージド機能が有効になっているオペレーションに適用されます。
• Apache Iceberg 形式バージョン 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 オーダーと線形並べ替えをサポートしていません。テーブルにこれらのプロパティが含まれている場合、統合の実行後にレイアウトが維持されるとは限りません。テーブルにこれらのプロパティが含まれている場合は、テーブル管理を有効にしないことをおすすめします。

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

• オープンソース エンジンからテーブルを作成または登録する場合、マネージド機能は、hour、day、month、year 変換（DATE フィールドの hour 変換を除く）を使用して、DATE、TIMESTAMP、TIMESTAMPTZ フィールド型のパーティショニングのみをサポートします。
• マネージド機能は、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	Lakehouse REST カタログ用に構成されたデフォルトの Cloud Storage バケットパスが、データファイルの書き込みに使用されます。
write.metadata.path	table location + /metadata	Lakehouse REST カタログ用に構成されたデフォルトの Cloud Storage バケットパスは、メタデータ ファイルの書き込みに使用されます。
write.delete.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、Copy-On-Write のみをサポートしています。
write.update.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、Copy-On-Write のみをサポートしています。
write.merge.mode	copy-on-write	BigQuery の書き込みジョブとテーブル管理ジョブは、Copy-On-Write のみをサポートしています。
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 日（604800000 ミリ秒）までをおすすめします。テーブル管理ジョブは、指定した期間よりも古いスナップショットを削除します。
history.expire.min-snapshots-to-keep	1	任意の正の整数に構成できます。テーブル管理ジョブは、少なくともこの数のスナップショットを保持します。

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

次のステップ

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