將 BigQuery 資料同步至 AlloyDB

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

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

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

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

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

效能和運作考量

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

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

事前準備

  1. 請先瞭解 bigquery_fdw 如何處理 BigQuery 資料類型和資料欄對應，因為 alloydb_sync 擴充功能會使用 bigquery_fdw 連線至 BigQuery。
  2. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  3. 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

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

  5. 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

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

  7. 啟用建立及連線至 AlloyDB 時所需的 Cloud API。

    啟用 API

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

  9. 在「啟用 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。

  10. 請確認您有現成的 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 的連線。如果您使用 Google Cloud 控制台，AlloyDB 會自動執行這些步驟。

  1. 建立擴充功能。

    1. 按照「將 psql 用戶端連線至執行個體」一文中的操作說明，使用 psql 用戶端連線至 AlloyDB 執行個體。

    2. 執行下列指令：

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;

  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 資料表以進行一次性匯出

您可以透過Google Cloud 控制台或 psql，同步處理 BigQuery 資料表並一次性匯出資料。

使用 Google Cloud 控制台

如要使用Google Cloud 控制台將 BigQuery 資料表同步至 AlloyDB，請按照下列步驟操作：

  1. 在 Google Cloud 控制台開啟 BigQuery 頁面。

    前往 BigQuery 頁面

  2. 點選左側窗格中的 「Explorer」。

    如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

  3. 在「Explorer」窗格中展開專案，按一下「Datasets」(資料集)，然後按一下資料集。

  4. 依序按一下「總覽」>「表格」，然後選取表格。

  5. 在詳細資料窗格中，依序點選「上傳」 「匯出 / 同步」>「AlloyDB (僅匯出一次或同步處理)」。

  6. 在「選擇目標叢集」下方，選取下列任一選項：

    • 選取「使用現有叢集」，將 BigQuery 表格匯出至現有 AlloyDB 叢集。接著，請執行下列操作：

      1. 選取主要 AlloyDB 叢集。

      2. 選取目的地 AlloyDB 資料庫。

      3. 選取目的地 AlloyDB 資料表的結構定義。

      4. 指定目的地 AlloyDB 資料表的名稱。

      5. 在「同步頻率」部分，選取「僅一次」，建立 BigQuery 資料表的副本。

      6. 按一下「設定匯出作業」。

      同步設定完成後，您可以使用提供的 SQL 陳述式追蹤匯入工作，以及查詢匯入的資料表。按一下「查詢」，系統會將您導向 AlloyDB Studio 中匯入的資料表。

    • 選取「建立新叢集」，將 BigQuery 資料表匯出至新的 AlloyDB 叢集。然後執行下列操作：

      1. 按一下「設定匯出作業」。

      2. 在「重新導向至 AlloyDB」對話方塊中，選取「重新導向」。

      3. 選取叢集類型，包括「免費試用叢集」或「已佈建的叢集」。

      4. 按一下「繼續」。

      5. 在「Sync Configuration」(同步設定) 中，選取預設 postgres 目的地 AlloyDB 資料庫、目的地 AlloyDB 資料表的預設 public 結構定義，並指定目的地 AlloyDB 資料表的名稱。

        在「同步頻率」部分，選取「僅一次」，建立 BigQuery 資料表的副本。

      6. 按一下「繼續」。

      7. 設定叢集。如要進一步瞭解每個欄位，請參閱「建立新的叢集和主要執行個體」。

      8. 點選「建立叢集」。

      同步設定完成後，請前往 AlloyDB Studio 查詢匯入的資料表。

使用 psql 一次性同步 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 資料表，定期匯出資料

您可以透過Google Cloud 控制台或 psql，同步處理 BigQuery 資料表，定期匯出資料。

使用 Google Cloud 控制台

如要使用Google Cloud 控制台將 BigQuery 資料表同步至 AlloyDB，請按照下列步驟操作：

  1. 在 Google Cloud 控制台開啟 BigQuery 頁面。

    前往 BigQuery 頁面

  2. 點選左側窗格中的 「Explorer」。

    醒目顯示的「Explorer」窗格按鈕。

    如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

  3. 在「Explorer」窗格中展開專案，按一下「Datasets」(資料集)，然後按一下資料集。

  4. 依序按一下「總覽」>「表格」，然後選取表格。

  5. 在詳細資料窗格中，依序點選「上傳」 「匯出 / 同步」>「AlloyDB (僅匯出一次或同步處理)」。

  6. 在「選擇目標叢集」下方，選取下列任一選項：

    • 選取「使用現有叢集」，將 BigQuery 表格匯出至現有 AlloyDB 叢集。接著，請執行下列操作：

      1. 選取主要 AlloyDB 叢集。

      2. 選取目的地 AlloyDB 資料庫。

      3. 選取目的地 AlloyDB 資料表的結構定義。

      4. 指定目的地 AlloyDB 資料表的名稱。

      5. 在「同步頻率」部分，選取時間範圍，定期同步處理 BigQuery 資料表，例如「每小時」、「每六小時」。

      6. 按一下「設定匯出作業」。

      同步設定完成後，您可以使用提供的 SQL 陳述式追蹤匯入工作，並查詢匯入的資料表。按一下「查詢」，系統會將您導向 AlloyDB Studio 中匯入的資料表。

    • 選取「建立新叢集」，將 BigQuery 資料表匯出至新的 AlloyDB 叢集。然後執行下列操作：

      1. 按一下「設定匯出作業」。

      2. 在「重新導向至 AlloyDB」對話方塊中，選取「重新導向」。

      3. 選取叢集類型，包括「免費試用叢集」或「已佈建的叢集」。

      4. 按一下「繼續」。

      5. 在「Sync Configuration」(同步設定) 中，選取預設 postgres 目的地 AlloyDB 資料庫、目的地 AlloyDB 資料表的預設 public 結構定義，並指定目的地 AlloyDB 資料表的名稱。

        在「同步頻率」部分，選取「僅一次」，建立 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 版。
  • 如果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 串流讀取 (Storage Read API) 定價收費。

匯出資料之後，系統會因您在 AlloyDB 中儲存資料而向您收取費用。詳情請參閱 AlloyDB for PostgreSQL 定價。

後續步驟