BigQuery のリアルタイム データへの AlloyDB アクセスを構成する

このドキュメントでは、複雑な ETL（抽出、変換、読み込み）移行を実行せずに、AlloyDB から BigQuery のライブデータを直接クエリできる機能であるレイクハウス連携を実装する方法について説明します。レイクハウス フェデレーションは、運用データストアと分析データストアを統合し、複雑でエラーが発生しやすいデータ パイプラインの必要性を排除します。詳細については、リアルタイム データへのアクセスの概要をご覧ください。

AlloyDB と BigQuery を統合すると、トランザクション データベースとデータ ウェアハウス間のデータフローがシームレスになり、リアルタイム分析がサポートされ、強力なインタラクティブ アプリケーションを構築できます。

この統合を使用すると、AlloyDB でクエリを実行して、BigQuery データにリアルタイムでアクセスできます。AlloyDB のテーブルと、BigQuery データセットを参照する外部テーブルの間で結合を実行できます。これは、BigQuery から最新のデータを移動せずに取得する必要がある場合に便利です。

このページでは、AlloyDB クラスタとプライマリ インスタンスを作成しており、BigQuery のデータセットとテーブルがあることを前提としています。詳細については、データセットの作成とテーブルの作成と使用をご覧ください。

始める前に

  1. AlloyDB for PostgreSQL インスタンスで bigquery_fdw.enabled フラグを有効にします。
  2. サポートされているデータ型について理解しておいてください。
  3. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    10.

  10. AlloyDB の作成と接続に必要な Cloud APIs を有効にします。

    API を有効にする

  11. [プロジェクトを確認] の手順で、[次へ] をクリックして、変更するプロジェクトの名前を確認します。

  12. [API を有効にする] の手順で、[有効にする] をクリックして、次の機能を有効にします。

    • AlloyDB API
    • Compute Engine API
    • Cloud Resource Manager API
    • Service Networking API
    • BigQuery Storage API
    • BigQuery API

    AlloyDB と同じ Google Cloud プロジェクトにある VPC ネットワークを使用して AlloyDB へのネットワーク接続を構成する場合は、Service Networking API が必要です。

    別の Google Cloud プロジェクトにある VPC ネットワークを使用して AlloyDB へのネットワーク接続を構成する場合は、Compute Engine API と Cloud Resource Manager API が必要です。

必要なロール

AlloyDB クラスタのサービス アカウントに BigQuery データセットへの読み取りアクセス権を付与するには、次の権限が必要です。詳細については、AlloyDB に BigQuery データセットへのアクセス権を付与するをご覧ください。

  • BigQuery データ閲覧者（roles/bigquery.dataViewer）、または bigquery.tables.get 権限と bigquery.tables.getData 権限を含むカスタムロール。このロールをテーブルまたはビューに付与すると、テーブルまたはビューからデータとメタデータを読み取る権限が付与されます。
  • BigQuery 読み取りセッション ユーザー（roles/bigquery.readSessionUser）、または bigquery.readsessions.create 権限と bigquery.readsessions.getData 権限を含むカスタムロール。読み取りセッションを作成および使用する権限が付与されます。

  • BigQuery ジョブユーザー（roles/bigquery.jobUser）、または bigquery.jobs.create 権限を含むカスタムロール。BigQuery API を使用して、プロジェクト内でジョブ（クエリを含む）を実行する権限を付与します。このロールは、Resource Manager リソース（プロジェクト、フォルダ、組織）にのみ付与できます。別のランタイム プロジェクトを指定すると、ジョブはデータ プロジェクトではなく、そのプロジェクトで実行されます。つまり、ランタイム プロジェクトに対するジョブ ユーザーのロールを付与する必要があります。

  • ストレージ オブジェクト閲覧者（roles/storage.objectViewer）、または storage.objects.get 権限を持つカスタムロール。BigQuery 外部テーブルにアクセスする権限を付与します。プロジェクト レベルまたはバケットレベルで付与する必要があります。

AlloyDB に BigQuery データセットへのアクセス権を付与する

レイクハウス フェデレーションに必要なロールと権限を有効にしたら、AlloyDB クラスタのサービス アカウントに BigQuery データセットへのアクセス権を付与する必要があります。

AlloyDB Studio を使用して BigQuery テーブルを接続すると、 Google Cloud コンソールによって、必要な権限がクラスタ サービス アカウントに自動的に付与されます。

gcloud CLI を使用してアクセス権を付与する手順は次のとおりです。

gcloud

gcloud CLI を使用するには、Google Cloud CLI をインストールして初期化するか、Cloud Shell を使用します。

  1. gcloud CLI を開きます。gcloud CLI がインストールされていない場合は、gcloud CLI をインストールして初期化するか、Cloud Shell を使用します。

  2. gcloud beta alloydb clusters describe コマンドを実行します。

    gcloud beta alloydb clusters describe CLUSTER --region=REGION

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

    • CLUSTER: AlloyDB クラスタ ID。
    • REGION: AlloyDB クラスタのロケーション（例: asia-east1、us-east1）。リージョンの一覧については、AlloyDB のロケーションをご覧ください。

    出力には、このクラスタのサービス アカウントである serviceAccountEmail フィールドが含まれます。サービス アカウントは、[クラスタの概要] ページでも確認できます。

  3. 必要な権限を付与します。詳細については、IAM を使用してリソースへのアクセスを制御するをご覧ください。

    クラスタのサービス アカウントに必要な権限がない場合、BigQuery テーブルに対してクエリを実行すると、次のエラーが表示されます。

    • The user does not have bigquery.readsessions.create permissions
    • Permission bigquery.tables.get denied on table
    • Permission bigquery.tables.getData denied on table

拡張機能の設定

拡張機能を構成する手順は次のとおりです。

コンソール

  1. [クラスタ] ページに移動します。

    [クラスタ] に移動

  2. 使用するクラスタの ID をクリックします。

  3. ナビゲーション メニューで [AlloyDB Studio] をクリックします。

  4. データベースにログインします。

  5. [エクスプローラ] ペインで、関連するスキーマを開きます。

  6. [BigQuery テーブル] の横にある [アクション] メニューをクリックし、[BigQuery テーブルを接続] をクリックします。

  7. [BigQuery テーブルを接続] ペインで、ソース プロジェクト、ソース データセット、テーブルを選択します。

  8. [列の確認と選択] テーブルには、選択したテーブルの列が表示されます。マッピングする列を選択します。

  9. [テーブル名] フィールドに、外部テーブルの名前を入力します。

  10. 省略可: [SQL コマンドを表示] をクリックして、生成されたコマンドを表示します。

  11. [テーブルを接続] をクリックします。進行状況を示すダイアログが表示されます。プロセスが完了すると、AlloyDB の任意のテーブルにクエリを実行するのと同じ方法で、テーブルにクエリを実行できます。

psql

  1. 拡張機能を作成します。

    1. psql クライアントをインスタンスに接続するの手順に沿って、psql クライアントを使用して AlloyDB インスタンスに接続します。または、AlloyDB Studio を使用することもできます。詳細については、 Google Cloud コンソールを使用してデータを管理するをご覧ください。

    2. 次のコマンドを実行します。

      CREATE EXTENSION bigquery_fdw;

  2. 外部サーバーを作成して、リモート BigQuery データセットの接続パラメータを定義します。

    CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw
  OPTIONS (runtime_project 'RUNTIME_PROJECT_ID');

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

    • BIGQUERY_SERVER_NAME: 外部サーバーの固有識別子。これは、特定のデータベースで 1 回定義します。BIGQUERY_SERVER_NAME は、実際のサーバー名に置き換えることができます。
    • RUNTIME_PROJECT_ID: 省略可。クエリを処理してコンピューティング費用を発生させる Google Cloudプロジェクトの ID。この ID を省略すると、クエリの料金はデータを保存するプロジェクトに請求されます。

  3. CREATE USER MAPPING コマンドを実行してユーザー マッピングを作成します。このコマンドは、外部サーバーに接続するローカル PostgreSQL ユーザーをマッピングします。

    CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;

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

    • USERNAME: 外部テーブルにアクセスするデータベース ユーザー名または IAM ユーザー。
    • BIGQUERY_SERVER_NAME: 作成した外部サーバーの固有識別子。

  4. CREATE FOREIGN TABLE コマンドを使用して、BigQuery でアクセスするテーブルに対応する外部テーブルを定義します。このコマンドを使用すると、リモート テーブルの構造を定義できます。外部テーブルには、BigQuery のソーステーブルのすべての列または列のサブセットを含めることができます。

    CREATE FOREIGN TABLE TABLENAME (
  COLUMN1_NAME DATA_TYPE,
  COLUMN2_NAME DATA_TYPE,
  ...
) SERVER BIGQUERY_SERVER_NAME OPTIONS (
  project 'BIGQUERY_PROJECT_ID',
  dataset 'BIGQUERY_DATASET_NAME',
  table ';BIGQUERY_TABLE_NAME',
  runtime_project 'RUNTIME_PROJECT_ID'
);

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

    • TABLENAME: ローカル AlloyDB データベース内の外部テーブルの名前。
    • COLUMNX_NAME: AlloyDB 列名。列名は、BigQuery ソーステーブルの対応する列の名前と完全に一致している必要があります。X は、複数の列でテーブルを作成できることを示します。名前は、BigQuery 列の正確な大文字と小文字の区別と一致している必要があります。BigQuery 列名に大文字が含まれている場合（employeeID など）、大文字と小文字が混在した文字または大文字を保持するには、AlloyDB 識別子を二重引用符で囲む必要があります（"employeeID" など）。
    • DATA_TYPE: 列のデータ型。外部テーブルの各列の DATA_TYPE を定義するときに、互換性のある PostgreSQL 型であることを確認します。BigQuery 型の変換方法の詳細については、データ型のマッピングをご覧ください。
    • BIGQUERY_SERVER_NAME: 作成した外部サーバーの固有識別子。
    • BIGQUERY_PROJECT_ID: BigQuery データセットがあるプロジェクトの ID。
    • BIGQUERY_DATASET_NAME: テーブルの BigQuery データセットの名前。
    • BIGQUERY_TABLE_NAME: BigQuery テーブルの名前。
    • RUNTIME_PROJECT_ID: 省略可。クエリ実行の請求先となる Google Cloudプロジェクトの ID。テーブルレベルでこれを設定すると、サーバーレベルで定義されたランタイム プロジェクトがオーバーライドされます。

    外部テーブルを作成したら、AlloyDB の任意のテーブルにクエリを実行するのと同じ方法で、このテーブルにクエリを実行できます。

データ型マッピング

次の表で、BigQuery と AlloyDB のデータ型のマッピングについて確認してください。詳細については、連携クエリのデータ型に関する考慮事項をご覧ください。

次の表に、BigQuery と AlloyDB のデータ型のマッピングを示します。

BigQuery テーブルのデータ型 推奨される PostgreSQL 外部テーブルのデータ型

BOOLEAN

BOOLEAN

INTEGER (INT64)

BIGINT

FLOAT (FLOAT64)

DOUBLE PRECISION

STRING

VARCHAR

NUMERIC

NUMERIC(38, 9)

NUMERIC(P[, S])

NUMERIC(P, S)

BIGNUMERIC

NUMERIC(77, 38)

BIGNUMERIC(P[, S])

NUMERIC(P, S)

DATE

DATE

TIMESTAMP

TIMESTAMPTZ

TIME

TIME

JSON

JSONB

BYTES

BYTEA

GEOGRAPHY

GEOGRAPHY(POINT), ...

詳細については、PostGIS_Geography をご覧ください。

DATETIME

TIMESTAMP

ARRAY

VECTOR(N)

N はベクトルの次元です。セッションで bigquery_fdw.enable_vector_downcasting フラグを設定する必要があります。AlloyDB の VECTOR 型は float4 型を使用するため、この変換で精度が低下する可能性があります。

詳細については、pgvector 拡張機能をご覧ください。

次のステップ