Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

BigQuery データを AlloyDB に同期する

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

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

AlloyDB では、次の方法で BigQuery データをインスタンスに移動できます。

1 回限りの同期: BigQuery テーブルの書き込み可能な独立したコピーを作成します。
定期的な同期（ミラーリング）: スケジュールに従って自動的に更新される読み取り専用のローカルテーブルを作成します（6 時間ごとや毎日など）。

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

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

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

始める前に

alloydb_sync 拡張機能は bigquery_fdw を使用して BigQuery に接続するため、bigquery_fdw が BigQuery のデータ型と列のマッピングを処理する方法を理解しておいてください。

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

API を有効にする
[プロジェクトを確認] の手順で、変更するプロジェクトの名前を確認して [次へ] をクリックします。
[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 が必要です。
データの同期元となる既存の 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 への接続を構成します。 Google Cloud コンソールを使用する場合、AlloyDB はこれらの手順を自動的に実行します。

拡張機能を作成します。
1. psql クライアントをインスタンスに接続するの手順に沿って、psql クライアントを使用して AlloyDB インスタンスに接続します。
2. 次のコマンドを実行します。
```
CREATE EXTENSION IF NOT EXISTS alloydb_sync;
```
  注: これらの拡張機能は、BigQuery データを同期するすべてのデータベースに作成する必要があります。
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 テーブルを同期する

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

Google Cloud コンソールを使用する

Google Cloud コンソールを使用して BigQuery テーブルを AlloyDB に同期するには:

Google Cloud コンソールで [BigQuery] ページを開きます。

[BigQuery] ページに移動
左側のペインで、 エクスプローラをクリックします。

左側のペインが表示されていない場合は、 左ペインを開くをクリックしてペインを開きます。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットをクリックします。
[概要] > [テーブル] をクリックし、テーブルを選択します。
詳細ペインで、[アップロード] [エクスポート / 同期] > [AlloyDB（1 回エクスポートまたは同期）] をクリックします。
[プロジェクトを選択] で、AlloyDB クラスタのプロジェクトを選択します。必要な権限がある場合は、現在の BigQuery プロジェクト以外のプロジェクトを選択できます。
[ターゲットクラスタを選択] で、次のいずれかのオプションを選択します。
- [既存のクラスタを使用する] を選択して、BigQuery テーブルを既存の AlloyDB クラスタにエクスポートします。次に、以下の操作を行います。
  1. プライマリ AlloyDB クラスタを選択します。
  2. 移行先の AlloyDB データベースを選択します。
  3. 宛先 AlloyDB テーブルのスキーマを選択します。
  4. 宛先 AlloyDB テーブルの名前を指定します。
  5. [同期の頻度] で [1 回のみ] を選択して、BigQuery テーブルのコピーを作成します。
  6. [エクスポートを設定] をクリックします。
  同期の設定が完了したら、提供された SQL ステートメントを使用して、インポートジョブを追跡し、インポートされたテーブルをクエリできます。[クエリ] をクリックして、AlloyDB Studio のインポートされたテーブルに移動します。
- [新しいクラスタを作成] を選択して、BigQuery テーブルを新しい AlloyDB クラスタにエクスポートします。次に、以下の操作を行います。
  1. [エクスポートを設定] をクリックします。
  2. [AlloyDB にリダイレクト] ダイアログで、[リダイレクト] を選択します。
  3. クラスタタイプとして、[無料トライアルクラスタ] または [プロビジョニング済みクラスタ] を選択します。
  4. [続行] をクリックします。
  5. [同期構成] で、デフォルトの postgres 送信先 AlloyDB データベース、送信先 AlloyDB テーブルのデフォルトの public スキーマを選択し、送信先 AlloyDB テーブルの名前を指定します。
    
    [同期の頻度] で [1 回のみ] を選択して、BigQuery テーブルのコピーを作成します。
  6. [続行] をクリックします。
  7. クラスタを構成します。各フィールドの詳細については、新しいクラスタとプライマリインスタンスを作成するをご覧ください。
  8. [クラスタを作成] をクリックします。
  同期の設定が完了したら、AlloyDB Studio に移動して、インポートしたテーブルをクエリします。

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

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 テーブルを同期する

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

Google Cloud コンソールを使用する

Google Cloud コンソールを使用して BigQuery テーブルを AlloyDB に同期するには:

Google Cloud コンソールで [BigQuery] ページを開きます。

[BigQuery] ページに移動
左側のペインで、 [エクスプローラ] をクリックします。

左側のペインが表示されていない場合は、 [左ペインを開く] をクリックしてペインを開きます。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、データセットをクリックします。
[概要] > [テーブル] をクリックし、テーブルを選択します。
詳細ペインで、[アップロード] [エクスポート / 同期] > [AlloyDB（1 回エクスポートまたは同期）] をクリックします。
[プロジェクトを選択] で、AlloyDB クラスタのプロジェクトを選択します。必要な権限がある場合は、現在の BigQuery プロジェクト以外のプロジェクトを選択できます。
[ターゲットクラスタを選択] で、次のいずれかのオプションを選択します。
- [既存のクラスタを使用する] を選択して、BigQuery テーブルを既存の AlloyDB クラスタにエクスポートします。次に、以下の操作を行います。
  1. プライマリ AlloyDB クラスタを選択します。
  2. 移行先の AlloyDB データベースを選択します。
  3. 宛先 AlloyDB テーブルのスキーマを選択します。
  4. 宛先 AlloyDB テーブルの名前を指定します。
  5. [同期の頻度] で、BigQuery テーブルの定期的な同期を作成する期間を選択します（[1 時間ごと]、[6 時間ごと] など）。
  6. [エクスポートを設定] をクリックします。
  同期の設定が完了したら、提供された SQL ステートメントを使用して、インポートジョブを追跡し、インポートされたテーブルをクエリできます。[クエリ] をクリックして、AlloyDB Studio のインポートされたテーブルに移動します。
- [新しいクラスタを作成] を選択して、BigQuery テーブルを新しい AlloyDB クラスタにエクスポートします。次に、以下の操作を行います。
  1. [エクスポートを設定] をクリックします。
  2. [AlloyDB にリダイレクト] ダイアログで、[リダイレクト] を選択します。
  3. クラスタタイプとして、[無料トライアルクラスタ] または [プロビジョニング済みクラスタ] を選択します。
  4. [続行] をクリックします。
  5. [同期構成] で、デフォルトの postgres 送信先 AlloyDB データベース、送信先 AlloyDB テーブルのデフォルトの public スキーマを選択し、送信先 AlloyDB テーブルの名前を指定します。
    
    [同期の頻度] で [1 回のみ] を選択して、BigQuery テーブルのコピーを作成します。
  6. [続行] をクリックします。
  7. クラスタを構成します。各フィールドの詳細については、新しいクラスタとプライマリインスタンスを作成するをご覧ください。
  8. [クラスタを作成] をクリックします。
  同期の設定が完了したら、AlloyDB Studio に移動して、インポートしたテーブルをクエリします。

定期的な同期を作成する

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 ビューに対してクエリを実行すると、処理されたレコード数や推定完了時間などの進行状況をモニタリングできます。

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');

データ型マッピング

alloydb_sync 拡張機能を使用して BigQuery から AlloyDB にデータを同期またはインポートすると、AlloyDB は BigQuery のデータ型をターゲットテーブル内の対応する PostgreSQL のデータ型にマッピングします。

移行元の BigQuery テーブルの列で、次のサポートされているデータ型が使用されていることを確認します。

次の表に、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` 拡張機能をご覧ください。

制限事項

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 ストリーミング読み取り（Storage Read API）の料金が課金されます。

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

次のステップ

詳細については、AlloyDB にデータをエクスポートする（リバース ETL）をご覧ください。
詳しくは、FDW を使用して BigQuery データをインプレースでクエリするをご覧ください。

BigQuery データを AlloyDB に同期する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

始める前に

必要なロール

拡張機能の設定

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

Google Cloud コンソールを使用する

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

例

on_exists パラメータ

主キーのサポート

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

Google Cloud コンソールを使用する

定期的な同期を作成する

例

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

ジョブ ステータスの確認

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

データ型マッピング

制限事項

料金

次のステップ

BigQuery データを AlloyDB に同期する

`on_exists` パラメータ

ジョブステータスの確認