BigQuery のテーブルで Lakehouse ランタイム カタログを使用する

このドキュメントでは、BigQuery テーブルと Managed Service for Apache Spark で Lakehouse ランタイム カタログを使用する方法の例を示します。

Lakehouse ランタイム カタログを使用すると、BigQuery から 標準（組み込み）テーブル、 BigQuery マネージド Apache Iceberg テーブル、 および 外部 Apache Iceberg テーブル を作成して使用できます。

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

Apache Iceberg V2 テーブルのみがサポートされています。Iceberg V1 テーブルはサポートされていません。既存の Iceberg V1 テーブルがある場合は、Lakehouse ランタイム カタログで使用する前に、V2 にアップグレードする必要があります（たとえば、ALTER TABLE catalog.schema.table SET TBLPROPERTIES ('format-version'='2'); を実行するか、同様のエンジン オペレーションを使用します）。

始める前に

  1. Google Cloud プロジェクトに対する課金を有効にします。詳しくは、プロジェクトで課金が有効になっているかどうかを 確認する方法をご覧ください。

  2. BigQuery API と Dataproc API を有効にします。

    API を有効にする

必要なロール

メタデータ ストアとして Lakehouse ランタイム カタログで Managed Service for Apache Spark を使用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • Apache Spark で Lakehouse ランタイム カタログ テーブルを作成する:
    • Dataproc ワーカー （roles/dataproc.worker）プロジェクトの Managed Service for Apache Spark サービス アカウントに対する
    • BigQuery データ編集者 （roles/bigquery.dataEditor）プロジェクトの Managed Service for Apache Spark サービス アカウントに対する
    • Storage オブジェクト ユーザー （roles/storage.objectUser）プロジェクトの Managed Service for Apache Spark サービス アカウントに対する
  • BigQuery で Lakehouse ランタイム カタログ テーブルに対してクエリを実行する:

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

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

テーブルに接続します。

  1. Google Cloud コンソールでデータセットを作成します。

    CREATE SCHEMA `PROJECT_ID`.DATASET_NAME;

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

    • PROJECT_ID: データセットを作成する　 Google Cloud 　プロジェクトの ID。
    • DATASET_NAME: データセットの名前。

  2. Cloud リソース接続を作成します。

  3. 標準の BigQuery テーブルを作成します。

    CREATE TABLE `PROJECT_ID`.DATASET_NAME.TABLE_NAME (name STRING,id INT64);

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

    • TABLE_NAME: テーブルの名前。

  4. 標準の BigQuery テーブルにデータを挿入します。

    INSERT INTO `PROJECT_ID`.DATASET_NAME.TABLE_NAME VALUES ('test_name1', 123),('test_name2', 456),('test_name3', 789);

  5. BigQuery マネージド Apache Iceberg テーブルを作成します。

    たとえば、テーブルを作成するには、次の CREATE ステートメントを実行します。

    CREATE TABLE `PROJECT_ID`.DATASET_NAME.ICEBERG_TABLE_NAME(
name STRING,id INT64
)
WITH CONNECTION `CONNECTION_NAME`
OPTIONS (
file_format = 'PARQUET',
table_format = 'ICEBERG',
storage_uri = 'STORAGE_URI');

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

    • ICEBERG_TABLE_NAME: マネージド Apache Iceberg テーブルの名前。例: iceberg_managed_table
    • CONNECTION_NAME: 接続の名前。これは前の手順で作成しました。例: myproject.us.myconnection
    • STORAGE_URI: 完全修飾の Cloud Storage URI。例: gs://mybucket/table

  6. BigQuery マネージド Apache Iceberg テーブルにデータを挿入します。

    INSERT INTO `PROJECT_ID`.DATASET_NAME.ICEBERG_TABLE_NAME VALUES ('test_name1', 123),('test_name2', 456),('test_name3', 789);

  7. 外部 Apache Iceberg テーブルを作成します。

    たとえば、外部 Apache Iceberg テーブルを作成するには、次の CREATE ステートメントを実行します。

    CREATE OR REPLACE EXTERNAL TABLE  `PROJECT_ID`.DATASET_NAME.READONLY_ICEBERG_TABLE_NAME
WITH CONNECTION `CONNECTION_NAME`
OPTIONS (
  format = 'ICEBERG',
  uris =
    ['BUCKET_PATH'],
  require_partition_filter = FALSE);

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

    • READONLY_ICEBERG_TABLE_NAME: 読み取り専用テーブルの名前。
    • BUCKET_PATH：外部テーブルのデータを含む Cloud Storage バケットへのパス（ ['gs://bucket_name/[folder_name/]file_name'] 形式）。

  8. Apache Spark から、標準テーブル、BigQuery マネージド Apache Iceberg テーブル、外部 Apache Iceberg テーブルに対してクエリを実行します。

    from pyspark.sql import SparkSession

# Create a spark session
spark = SparkSession.builder \
.appName("Lakehouse runtime catalog Iceberg") \
.config("spark.sql.catalog.CATALOG_NAME", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.CATALOG_NAME.catalog-impl", "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog") \
.config("spark.sql.catalog.CATALOG_NAME.gcp_project", "PROJECT_ID") \
.config("spark.sql.catalog.CATALOG_NAME.gcp_location", "LOCATION") \
.config("spark.sql.catalog.CATALOG_NAME.warehouse", "WAREHOUSE_DIRECTORY") \
.getOrCreate()
spark.conf.set("viewsEnabled","true")

# Use the Lakehouse runtime catalog
spark.sql("USE `CATALOG_NAME`;")
spark.sql("USE NAMESPACE DATASET_NAME;")

# Configure spark for temp results
spark.sql("CREATE namespace if not exists MATERIALIZATION_NAMESPACE");
spark.conf.set("materializationDataset","MATERIALIZATION_NAMESPACE")

# List the tables in the dataset
df = spark.sql("SHOW TABLES;")
df.show();

# Query the tables
sql = """SELECT * FROM DATASET_NAME.TABLE_NAME"""
df = spark.read.format("bigquery").load(sql)
df.show()

sql = """SELECT * FROM DATASET_NAME.ICEBERG_TABLE_NAME"""
df = spark.read.format("bigquery").load(sql)
df.show()

sql = """SELECT * FROM DATASET_NAME.READONLY_ICEBERG_TABLE_NAME"""
df = spark.read.format("bigquery").load(sql)
df.show()

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

    • WAREHOUSE_DIRECTORY: BigQuery マネージド Apache Iceberg テーブルと外部 Apache Iceberg テーブルに接続されている Cloud Storage フォルダの URI。
    • CATALOG_NAME: 使用しているカタログの名前。
    • MATERIALIZATION_NAMESPACE: 一時的な結果を保存する名前空間。

  9. Managed Service for Apache Spark を使用して Apache Spark スクリプトを実行します。

    gcloud dataproc batches submit pyspark SCRIPT_PATH \
  --version=2.2 \
  --project=PROJECT_ID \
  --region=REGION \
  --deps-bucket=YOUR_BUCKET \

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

    • SCRIPT_PATH: バッチジョブが使用するスクリプトのパス。
    • PROJECT_ID: バッチジョブを実行する Google Cloud プロジェクトの ID。
    • REGION: ワークロードが実行されるリージョン。
    • YOUR_BUCKET: ワークロードの依存関係をアップロードする Cloud Storage バケットのロケーション。バケットの gs:// URI 接頭辞は必要ありません。バケットパスまたはバケット名（mybucketname1 など）を指定できます。

次のステップ