將 BigQuery 資料同步至 AlloyDB

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

如要瞭解如何取得這個版本，請參閱 存取權要求頁面。

注意： 同步資料功能僅支援 PostgreSQL 第 18 版。

本頁說明如何將 BigQuery 中的資料表同步至 AlloyDB for PostgreSQL 執行個體。

將 BigQuery 的分析資料同步到 AlloyDB 後，您就能建構作業系統，並透過低延遲的交易存取權存取資料湖泊，進而獲益。與外部資料包裝函式 (FDW) 不同，同步資料表會將資料移至 AlloyDB 儲存空間，以發揮最高效能，而不是在原地查詢資料。

AlloyDB 提供下列方法，可將 BigQuery 資料移至執行個體：

• 單次同步：建立 BigQuery 資料表的可寫入獨立副本。

• 定期同步 (鏡像)：建立唯讀本機資料表，並依排程自動重新整理，例如每 6 小時或每天重新整理。

效能和運作考量

使用 BigQuery 同步資料表時，請注意下列事項：

• 資源用量：資料轉移作業會耗用 CPU 和記憶體。如果是非常大的資料表，建議您在離峰時段安排同步作業，以免影響主要交易工作負載。
• 資料可視性：在取代作業期間，系統會預先捨棄並重新建立現有的目標資料表。匯入期間的查詢一開始會看到空白資料表，接著批次交易提交後，新匯入的資料會逐步顯示。

事前準備

1. 請先瞭解 bigquery_fdw 如何處理 BigQuery 資料類型和資料欄對應，因為 alloydb_sync 擴充功能會使用 bigquery_fdw 連線至 BigQuery。
登入 Google Cloud 帳戶。如果您是 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 API。

   啟用 API

3. 如要確認要變更的專案名稱，請在「確認專案」步驟中按一下「下一步」。

4. 在「啟用 API」步驟中，點選「啟用」，啟用下列項目：

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

   如要使用與 AlloyDB 位於相同 Google Cloud 專案的虛擬私有雲網路，設定 AlloyDB 的網路連線，就必須啟用 Service Networking API。

   如要使用位於不同 Google Cloud 專案的 VPC 網路，設定 AlloyDB 的網路連線，則必須使用 Compute Engine API 和 Cloud Resource Manager API。

5. 請確認您有現成的 BigQuery 資料表，可從中同步資料。詳情請參閱「建立及使用 BigQuery 資料表」。

必要的角色

如要將 BigQuery 資料集存取權授予 AlloyDB 叢集服務帳戶，您必須具備下列權限：

• 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 伺服器的專屬 ID。在特定資料庫中定義一次即可。 你可以將 BIGQUERY_SERVER_NAME 替換成伺服器名稱。

同步 BigQuery 資料表以進行一次性匯出

您可以使用 psql 同步處理 BigQuery 資料表，進行一次性匯出。

使用 psql 一次性同步 BigQuery 資料表

注意： alloydb_sync.import_bq_table() 函式會建立可寫入的 AlloyDB 資料表，但不會自動重新整理 BigQuery 中的資料。

如要建立可編輯的 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 參數

如果 AlloyDB 中已存在目的地資料表，on_exists 參數會決定函式如何處理同步：

• 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() 函式會傳回工作 UUID，您可以比對 alloydb_sync.job_status 檢視畫面中的 import_id。

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 版。
• 如果DROPalloydb_sync擴充功能，您必須先重新啟動執行個體，才能再次建立擴充功能。
• 同步作業會在交易中執行。如果匯入工作遭到中斷或失敗，系統會還原匯入的資料。
• 如果兩位使用者同時啟動同步工作，且目標資料表相同，資料表可能會互相覆寫。
• 如果新註冊的同步資料表在初始背景匯入期間發生任何中斷，該資料表會保持不完整，直到下一個排定的重新整理間隔為止。如要解決這個問題，請使用 alloydb_sync.delete_bq_sync_table() 函式刪除同步資料表，然後重新建立。
• 系統不支援同步處理複雜的 BigQuery 類型，例如 ARRAY、BYTES、VECTOR 和 GEOGRAPHY。如需完整清單，請參閱「支援的 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 資料。