テーブルをクエリすると、Lakehouse ランタイム カタログで管理されているメタデータを使用して、基盤となる Cloud Storage ファイルからデータが読み取られます。
クエリは、Spark や Trino などのオープンソース エンジンから実行することも、4 つの部分からなるテーブル名構文（P.C.N.T 構文）を使用して BigQuery から直接実行することもできます。
始める前に
-
BigLake API を有効にします（有効になっていない場合）。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。 - Apache Iceberg REST カタログ エンドポイントを使用して Lakehouse ランタイム カタログを設定します。
必要なロール
テーブルに対してクエリを実行するために必要な権限を取得するには、プロジェクトとストレージ バケットに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
認証情報自動販売モードでテーブルデータを読み取る: BigLake 閲覧者（
roles/biglake.viewer）- プロジェクト -
認証情報ベンディング モード以外でテーブルデータを読み取る:
- BigLake 閲覧者（
roles/biglake.viewer）- プロジェクト - Storage オブジェクト閲覧者（
roles/storage.objectViewer）- Cloud Storage バケット
- BigLake 閲覧者（
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
テーブルの機能とサポート
Lakehouse ランタイム カタログでテーブルを使用する場合は、さまざまなテーブルタイプとそのオプトイン機能を理解しておくと役立ちます。Apache Iceberg テーブルの使用方法の詳細については、Apache Iceberg テーブルの概要をご覧ください。
サポートされている Iceberg テーブル
Apache Iceberg V2（一般提供）テーブルと V3（プレビュー）テーブルのみがサポートされています。Iceberg V1 テーブルはサポートされていません。既存の V1 テーブルをアップグレードするには、Iceberg V1 テーブルを V2 にアップグレードするをご覧ください。
テーブル オプションを使用する（プレビュー）
特定のテーブル プロパティを構成することで、BigQuery データ操作言語（DML）や自動テーブル管理などの BigQuery マネージド機能を使用するようにオプトインできます。これらの機能は、テーブルが作成される場所に応じて異なる方法で有効になります。
- BigQuery から: BigQuery DML と自動テーブル管理はデフォルトで有効になっています。
- オープンソース エンジンから: オプトインするには、テーブル プロパティを明示的に構成する必要があります。詳細については、テーブル オプションを構成するをご覧ください。
BigQuery からテーブルをクエリする場合、標準の Iceberg テーブルと、BigQuery のマネージド機能が有効になっているテーブルにアクセスできます。詳しい手順については、テーブル オプションを構成するをご覧ください。
テーブルに対してクエリを実行する
テーブルからすべてのデータを選択します。
Spark
spark.sql("SELECT * FROM TABLE_NAME;").show()
Trino
SELECT * FROM TABLE_NAME;
BigQuery
BigQuery から Lakehouse ランタイム カタログの Apache Iceberg テーブルにクエリを実行するには、クエリで 4 つの部分からなるテーブル名を PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME の形式で使用します。
SELECT * FROM `PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;
次の値を置き換えます。
PROJECT_NAME: Lakehouse ランタイム カタログ内のカタログを所有するGoogle Cloud プロジェクト。クエリの料金は、 Google Cloud コンソールで選択したGoogle Cloud プロジェクトに請求されます。CATALOG_ID: カタログの作成時に指定された Lakehouse ランタイム カタログの ID。この識別子は、BigQuery クエリでカタログ名として使用されます。この識別子は、Cloud Storage バケットの名前でもあります。
たとえば、カタログを保存するためにバケットを作成し、
iceberg-bucketという名前を付けた場合、カタログ名とバケット名の両方がiceberg-bucketになります。これは、後で P.C.N.T 構文を使用して BigQuery でカタログをクエリするときに使用されます。例:my-project.catalog_id.quickstart_namespace.quickstart_tableNAMESPACE_OR_SCHEMA_NAME: Spark を使用している場合はテーブルの名前空間、Trino を使用している場合はテーブル スキーマ名。TABLE_NAME: テーブルの名前。
タイムトラベルを使用したクエリ
タイムトラベルを使用して、マネージド Apache Iceberg テーブルから過去のデータをクエリできます。BigQuery からは FOR
SYSTEM_TIME AS OF 句を使用して、Spark などのオープンソース エンジンからはスナップショット ID、タイムスタンプ、タグ、ブランチを使用して、タイムトラベルを行うことができます。
タイムスタンプによるクエリ
特定のタイムスタンプのデータをクエリするには:
Spark
SELECT * FROM NAMESPACE.TABLE_NAME TIMESTAMP AS OF '2026-02-26 01:21:00';
BigQuery
SELECT * FROM `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` FOR SYSTEM_TIME AS OF '2026-02-26 01:21:00';
スナップショット ID でクエリする
特定の snapshot ID の時点のデータをクエリするには:
Spark
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;
タグによるクエリ
タグを作成し、そのタグの時点のデータをクエリするには:
Spark
-- Create tag 'historical-snapshot'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE TAG 'historical-snapshot' AS OF VERSION 123456789012345;
-- Query by tag
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'historical-snapshot';
ブランチでクエリを実行する
ブランチを作成し、そのブランチのデータをクエリするには:
Spark
-- Create branch 'audit-branch'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE BRANCH 'audit-branch' AS OF VERSION 123456789012345;
-- Query by branch
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'audit-branch';
次のステップ
- テーブルを変更する方法を学習する。