BigQuery データを AlloyDB に同期する

プレビュー

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

このリリースへのアクセスについては、 アクセス リクエスト ページをご覧ください。

注: 同期データ機能は、PostgreSQL バージョン 18 でのみサポートされています。

このページでは、BigQuery から AlloyDB for PostgreSQL インスタンスにテーブルを同期する方法について説明します。

BigQuery から AlloyDB に分析データを同期することで、データレイクへの低レイテンシのトランザクション アクセスを利用できる運用システムを構築できます。同期テーブルは、データをその場でクエリする 外部データラッパー（FDW） とは異なり、パフォーマンスを最大化するためにデータを AlloyDB ストレージに移動します。

AlloyDB には、BigQuery データをインスタンスに移動する方法がいくつかあります。

• 1 回限りの同期: BigQuery テーブルの書き込み可能な独立したコピーを作成します。

• 定期的な同期（ミラーリング）: スケジュール（6 時間ごと、毎日など）で自動的に更新される読み取り専用のローカル テーブルを作成します。

パフォーマンスと運用に関する考慮事項

BigQuery 同期テーブルを使用する場合は、次の点を考慮してください。

• リソースの使用量: データの移動には CPU とメモリが消費されます。非常に大きなテーブルの場合は、プライマリ トランザクション ワークロードに影響を与えないように、オフピーク時に同期をスケジュールすることを検討してください。
• データの可視性: 置換オペレーション中、既存のターゲット テーブルは事前に削除され、再作成されます。インポート中のクエリでは、最初は空のテーブルが表示され、バッチ トランザクションがコミットされると、新しくインポートされたデータが段階的に表示されます。

始める前に

1. alloydb_sync 拡張機能は bigquery_fdw を使用して BigQuery に接続するため、bigquery_fdw が BigQuery のデータ型と列のマッピングを処理する方法を理解しておいてください。
アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

   API を有効にする

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

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

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

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

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

5. データを同期する既存の BigQuery テーブルがあることを確認します。詳細については、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 からテーブルを同期する前に、必要な拡張機能を有効にして、BigQuery への接続を構成します。

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

   1. psql クライアントをインスタンスに接続するの手順に沿って、psql クライアントを使用して AlloyDB インスタンスに接続します。

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

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;
      

      注: これらの拡張機能は、BigQuery データを 同期するすべてのデータベースに作成する必要があります。

2. AlloyDB が BigQuery で認証できるように、ユーザー マッピングを作成します。

   CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
   CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;
   

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

   • USER: BigQuery テーブルにアクセスするデータベース ユーザー名または IAM ユーザー。
   • BIGQUERY_SERVER_NAME: BigQuery サーバーの一意の識別子。これは、特定のデータベースで 1 回定義します。 BIGQUERY_SERVER_NAME は、実際のサーバー名に置き換えることができます。

1 回限りのエクスポート用に BigQuery テーブルを同期する

psql を使用して、1 回限りのエクスポート用に BigQuery テーブルを同期できます。

psql を使用して BigQuery テーブルを 1 回同期する

**注:** alloydb_sync.import_bq_table() 関数は、BigQuery からデータを自動的に更新しない書き込み可能な AlloyDB テーブルを作成します。

BigQuery データの編集可能なコピーを作成するには、 psql を使用して alloydb_sync.import_bq_table 関数を実行します。

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

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

• PROJECT_ID: BigQuery データセットがあるプロジェクトの ID。
• DATASET_ID: テーブルの BigQuery データセットの名前。4 部構成の名前を持つ Iceberg テーブルの場合、これは Catalog.Namespace です。
• TABLE_ID: BigQuery テーブルまたはビューの名前。
• ALLOYDB_DESTINATION_TABLE_NAME: AlloyDB データベース内のローカル テーブルの名前。このテーブルにデータを作成してインポートします。 スキーマ名を含めることができます（例: public.local_sales）。
• ON_EXISTS: 宛先テーブルがすでに存在する場合に使用する戦略。
• PRIMARY_KEY_COLUMN: 主キーとして使用する列名のリスト（省略可）。

例

次の例では、BigQuery データセットから transactions という名前のテーブルを public.local_sales という名前の新しい AlloyDB テーブルに同期する方法を示します。

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);

on_exists パラメータ

on_exists パラメータは、宛先テーブルが AlloyDB にすでに存在する場合に、関数が同期を処理する方法を決定します。

• error: デフォルトのオプション。宛先テーブルがすでに存在する場合、同期を停止します。
• skip: 宛先テーブルがすでに存在する場合、同期をスキップします。
• replace: 既存のローカル テーブルを BigQuery の新しいデータに置き換えます。

主キーのサポート

省略可能な primary_key パラメータをテキスト配列として指定すると、AlloyDB は指定された列を主キーとしてテーブルを作成します。

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

定期的なエクスポート用に BigQuery テーブルを同期する

psql を使用して、定期的なエクスポート用に BigQuery テーブルを同期できます。

定期的な同期を作成する

BigQuery データと同期された読み取り専用テーブルを維持するには、psql を使用して alloydb_sync.create_bq_sync_table 関数を実行します。

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

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

• PROJECT_ID.DATASET_ID.TABLE_ID:BigQuery テーブルまたはビューの完全修飾名。プロジェクト ID、データセット ID、テーブル ID をピリオドで区切ります。4 部構成の名前を持つ Iceberg テーブルの場合、DATASET_ID は Catalog.Namespace として表されます。 例: my-gcp-project.sales_data.transactions。
• ALLOYDB_DESTINATION_TABLE_NAME: AlloyDB データベース内のローカル テーブルの名前。このテーブルにデータを作成して同期します。
• REFRESH_INTERVAL: AlloyDB が BigQuery からデータを定期的に更新する間隔（例: 12 hours）。
• ON_EXISTS: 宛先テーブルがすでに存在する場合に使用する戦略。
• PRIMARY_KEY_COLUMN: 主キーとして使用する列名のリスト（省略可）。

例

次の例では、12 時間ごとに更新される顧客プロファイル ミラーを作成する方法を示します。

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

ジョブのモニタリングと管理

同期を開始したら、その進行状況をモニタリングしてジョブを管理できます。

ジョブ ステータスの確認

大規模な同期には時間がかかることがあります。job_status ビューに対してクエリを実行すると、処理されたレコード数や完了予定時刻などの進行状況をモニタリングできます。

**注:** alloydb_sync.import_bq_table() 関数は、alloydb_sync.job_status ビューの import_id と照合できるジョブ UUID を返します。

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

たとえば、ジョブをキャンセルするには、次のコマンドを実行します。

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

同期ジョブを停止して削除する

BigQuery テーブルのミラーリングを停止してローカル テーブルを削除するには、alloydb_sync.delete_bq_sync_table 関数を使用します。

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

重要: レプリケートされたテーブルを削除するには、標準の PostgreSQL DROP TABLE コマンドではなく、この関数を使用する必要があります。この関数を使用せずに同期テーブルを手動で削除すると、バックグラウンド スケジューラ フックが削除されず、スケジューラでエラーが継続的に発生し、バックグラウンド ワーカー スロットが消費される可能性があります。

制限事項

BigQuery からテーブルを同期する場合、次の制限が適用されます。

• この機能は、PostgreSQL バージョン 18 でのみサポートされています。
• alloydb_sync 拡張機能を DROP する場合は、拡張機能を再度作成する前にインスタンスを再起動する必要があります。
• 同期はトランザクション内で実行されます。インポート ジョブが中断または失敗した場合、システムはインポートされたデータをロールバックします。
• 2 人のユーザーが同じターゲット テーブルを使用して同時に同期ジョブを開始すると、テーブルが相互に上書きされる可能性があります。
• 新しく登録された同期テーブルの最初のバックグラウンド インポート中に中断が発生した場合、テーブルは次のスケジュールされた更新間隔まで不完全なままになります。この問題を解決するには、alloydb_sync.delete_bq_sync_table() 関数を使用して同期テーブルを削除し、再作成します。
• ARRAY、BYTES、VECTOR、GEOGRAPHY などの複雑な BigQuery 型は、同期ではサポートされていません。完全なリストについては、 サポートされている BigQuery のデータ型と列のマッピングをご覧ください。
• レプリケートされたテーブルを手動で削除しないでください。alloydb_sync.delete_bq_sync_table() API 関数を使用して、テーブルと更新を安全に削除します。
• alloydb_sync 拡張機能を使用するデータベースを削除するには、DROP DATABASE ... WITH (FORCE) を使用する必要があります。
• インポートの実行中に Postgres データベースがクラッシュすると、メタデータが RUNNING 状態のままになり、以降のインポートがブロックされる可能性があります。ブロックを解除するには、 を手動で実行する必要があります。UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING';

料金

BigQuery から AlloyDB にデータを同期する場合は、BigQuery 容量コンピューティングの料金が適用されます。

データのエクスポート後、AlloyDB にデータを保存すると料金が発生します。詳細については、 AlloyDB for PostgreSQL の料金をご覧ください。

次のステップ

• AlloyDB へのデータのエクスポート（リバース ETL）について学習する。
• FDW を使用して BigQuery データをその場でクエリする方法について学習する。