BigLake メタストアで Iceberg リソースを管理する

BigLake メタストアは、データ処理エンジン間でデータ共有を可能にする単一の共有メタストアです。これにより、オープンソース ワークロード用に個別のメタストアを維持する必要がなくなります。

このドキュメントでは、BigLake Metastore で Iceberg リソースを作成、表示、変更、削除する方法について説明します。

始める前に

  1. Make sure that billing is enabled for your Google Cloud project.

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

  2. Enable the BigQuery, BigQuery Storage, and Dataproc APIs.

    Enable the APIs

  3. 省略可: BigLake metastore の仕組みと使用すべき理由を理解します。

必要なロール

BigLake メタストアで Iceberg リソースを管理するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

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

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

メタストア リソースを作成する

以降のセクションでは、BigLake メタストアにリソースを作成する方法について説明します。

Namespace を作成する

次のオプションのいずれかを選択します。

API

datasets.insert メソッドを使用して、渡す データセット リソースで ExternalCatalogDatasetOptions フィールドを指定します。

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

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

  • PROJECT_ID: ターゲット データセットを含むプロジェクトの ID
  • DATASET_ID: ターゲット データセットの ID
  • URI: データセット内のすべてのテーブルの Cloud Storage URI
  • LOCATION: データセットを作成する BigQuery のロケーション

Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: 新しい Namespace の名前

Terraform

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

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

  • PROJECT_ID: ターゲット データセットを含むプロジェクトの ID
  • DATASET_ID: ターゲット データセットの ID
  • LOCATION: データセットを作成する BigQuery のロケーション
  • URI: データセット内のすべてのテーブルの Cloud Storage URI

Iceberg テーブルを作成する

次のオプションのいずれかを選択します。

API

tables.insert メソッドを使用して、渡す テーブル リソースの ExternalCatalogTableOptions フィールドを指定します。

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

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

  • PROJECT_ID: ターゲット テーブルを含むプロジェクトの ID。
  • DATASET_ID: ターゲット テーブルを含むデータセットの ID。
  • TABLE_ID: ターゲット テーブルの ID。
  • METADATA_URI: 最新の Iceberg メタデータ ファイルの Cloud Storage URI。例: gs://mybucket/mytable/metadata/1234.metadata.json
  • CONNECTION_ID: Cloud Storage への接続の ID。

Spark SQL 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。
  • TABLE: 新しいテーブルの名前

Terraform

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

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

  • TABLE: ターゲット テーブルの名前。
  • STORAGE_URI: テーブルデータが保存されている Cloud Storage URI（gs:// で始まります）。
  • METADATA_URI: 最新の Iceberg メタデータ ファイルの Cloud Storage URI。例: gs://mybucket/mytable/metadata/1234.metadata.json

メタストア リソースを表示する

以降のセクションでは、BigLake メタストアのリソースを表示する方法について説明します。

Namespace を表示する

次のオプションのいずれかを選択します。

API

datasets.list メソッドを使用してすべての名前空間を表示するか、datasets.get メソッドを使用して定義された名前空間に関する情報を表示します。

Spark SQL

カタログ内のすべての Namespace を表示するには、次のステートメントを使用します。

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

SPARK_CATALOG は、Spark カタログの名前に置き換えます。

定義済みの名前空間に関する情報を表示するには、次のステートメントを使用します。

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。

テーブルの表示

次のオプションのいずれかを選択します。

API

名前空間内のすべてのテーブルを表示するには、tables.list メソッドを使用します。定義済みのテーブルに関する情報を表示するには、tables.get メソッドを使用します。

Spark SQL

Namespace 内のすべてのテーブルを表示するには、次のステートメントを使用します。

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。

定義済みのテーブルに関する情報を表示するには、次のステートメントを使用します。

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。
  • TABLE: テーブルの名前

メタストア リソースを変更する

以降のセクションでは、BigLake メタストア内のリソースを変更する方法について説明します。

名前空間を更新する

次のオプションのいずれかを選択します。

API

datasets.patch メソッドを使用して、データセット リソースの ExternalCatalogDatasetOptions フィールドを更新します。datasets.update メソッドはデータセット リソース全体を置き換えるため、推奨されません。

Spark SQL

ALTER DATABASE ステートメントを使用します。

Iceberg テーブルを更新する

次のオプションのいずれかを選択します。

API

tables.patch メソッドを使用して、テーブル リソースの ExternalCatalogTableOptions フィールドを更新します。tables.update メソッドはテーブル リソース全体を置き換えるため、おすすめしません。

スキーマまたはメタデータ ファイルを更新するには、tables.patch メソッドを使用して autodetect_schema プロパティを true に設定します。

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

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

  • PROJECT_ID: 更新するテーブルを含むプロジェクトの ID
  • DATASET_ID: 更新するテーブルを含むデータセットの ID
  • TABLE_ID: 更新するテーブルの ID

リクエストの本文で、各フィールドの更新後の値を指定します。たとえば、Iceberg テーブルのメタデータ ロケーションを更新するには、metadata_location フィールドの更新後の値を指定します。

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

METADATA_URI は、最新の Iceberg メタデータ ファイルの Cloud Storage URI に置き換えます。例: gs://mybucket/mytable/metadata/1234.metadata.json

Spark SQL

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

メタストア リソースを削除する

以降のセクションでは、BigLake メタストアのリソースを削除する方法について説明します。

名前空間を削除する

次のオプションのいずれかを選択します。

API

datasets.delete メソッドを使用します。deleteContents パラメータを true に設定して、Namespace 内のテーブルを削除します。

Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。

テーブルの削除

次のオプションのいずれかを選択します。

API

tables.delete メソッドを使用して、テーブルの名前を指定します。この方法では、Cloud Storage 内の関連ファイルは削除されません。

Spark SQL

テーブルを削除するだけの場合は、次のステートメントを使用します。

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。
  • TABLE: 削除するテーブルの名前

Cloud Storage でテーブルと関連ファイルを削除するには、次のステートメントを使用します。

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

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

  • SPARK_CATALOG: Spark カタログの名前
  • NAMESPACE: Namespace の名前。
  • TABLE: 削除するテーブルの名前

次のステップ