Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將 BigQuery 資料匯入 AlloyDB

您可以從 BigQuery 內建資料表、具體化檢視區塊和 BigQuery 檢視區塊，以及 BigLake 外部資料表 (例如 Apache Iceberg 代管資料表) 和標準外部資料表，將資料匯入 AlloyDB for PostgreSQL。Iceberg 是開放式資料表格式，用於管理及交換資料。

匯入資料後，您就不必建構及維護複雜且容易出錯的資料管道，手動將資料從 BigQuery 移回 AlloyDB。詳情請參閱「資料同步總覽」。

本頁假設您已擁有 AlloyDB 叢集和主要執行個體，以及 BigQuery 資料集和資料表。詳情請參閱「建立資料集」和「建立及使用資料表」。

事前準備

在 AlloyDB 執行個體上設定 bigquery_fdw.enabled 旗標。
請參閱資料類型對應關係，瞭解使用 bigquery_fdw 時，BigQuery 型別在 PostgreSQL 中的表示方式。
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.
Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.
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

如要建立及連線至 AlloyDB，請啟用必要的 Cloud API。

啟用 API
在「確認專案」步驟中，按一下「下一步」，確認要變更的專案名稱。
在「啟用 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。

必要的角色

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

BigQuery 資料檢視者 (roles/bigquery.dataViewer) 或任何具有 bigquery.tables.get 和 bigquery.tables.getData 權限的自訂角色。如果授予資料表或檢視表的權限，這個角色可提供從資料表或檢視表讀取資料和中繼資料的權限。
BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser) 或具備 bigquery.readsessions.create 和 bigquery.readsessions.getData 權限的任何自訂角色。可建立及使用讀取工作階段。

將 BigQuery 資料集存取權授予 AlloyDB

在 AlloyDB 叢集上設定 bigquery_fdw 擴充功能後，請將 BigQuery 資料集存取權授予 AlloyDB 叢集服務帳戶。

如要使用 gcloud CLI，可以安裝及初始化 Google Cloud CLI，也可以使用 Cloud Shell。

開啟 gcloud CLI。如果沒有安裝 gcloud CLI，請安裝並初始化 gcloud CLI，或使用 Cloud Shell。
請執行 gcloud beta alloydb clusters describe 指令。
```
gcloud beta alloydb clusters describe CLUSTER --region=REGION
```
更改下列內容：
- CLUSTER：AlloyDB 叢集 ID。
- REGION：AlloyDB 叢集的位置，例如 asia-east1、us-east1。如需完整地區清單，請參閱 AlloyDB 地理位置。
輸出結果含有 serviceAccountEmail 欄位，這是叢集的服務帳戶。您也可以在「叢集詳細資料」頁面中找到服務帳戶。
授予必要權限。詳情請參閱「使用 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
注意： 如果未提供 bigquery.readsessions.getData，系統會傳回空白結果，不會發生錯誤。

設定擴充功能

建立擴充功能。
1. 按照「將 psql 用戶端連線至執行個體」一文中的操作說明，使用 psql 用戶端連線至 AlloyDB 執行個體。或者，您也可以使用 AlloyDB Studio。詳情請參閱「使用 Google Cloud 控制台管理資料」。
2. 執行下列指令：
```
CREATE EXTENSION bigquery_fdw;
```
  注意： 您必須在所有需要存取 BigQuery 資料集的資料庫中建立這個擴充功能。
建立外部伺服器，定義遠端 BigQuery 資料集的連線參數。
```
CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
```
更改下列內容：
- BIGQUERY_SERVER_NAME：外部伺服器的專屬 ID。在特定資料庫中定義一次即可。您可以將 BIGQUERY_SERVER_NAME 替換成伺服器名稱。
執行 CREATE USER MAPPING 指令建立使用者對應，指定連線至外部伺服器時要使用的憑證。
```
CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;
```
更改下列內容：
- USERNAME：可存取外部資料表的使用者名稱或 IAM 使用者。如果是 IAM 使用者，名稱必須全部為小寫，且必須使用引號，因為名稱包含 @ 和 .) 等特殊字元。
- BIGQUERY_SERVER_NAME：您建立的外部伺服器專屬 ID。
使用 CREATE FOREIGN TABLE 指令，定義要存取 BigQuery 中資料表的外來資料表。這個指令可讓您定義遠端資料表的結構。外部資料表可以包含 BigQuery 來源資料表中的所有資料欄，也可以只包含部分資料欄。

注意： 請確認您使用的資料類型對應至支援的資料類型。詳情請參閱「資料類型對應」。
```
CREATE FOREIGN TABLE TABLENAME (
  COLUMNX_NAME DATA_TYPE,
  COLUMNX_NAME DATA_TYPE,
  ...
) SERVER  BIGQUERY_SERVER_NAME
  OPTIONS (project 'BIGQUERY_PROJECT_ID',
           dataset  'BIGQUERY_DATASET_NAME',
           table  'BIGQUERY_TABLE_NAME');
```
更改下列內容：
- TABLENAME：本機資料庫中的外部資料表名稱。
- COLUMNX_NAME：AlloyDB 資料欄名稱。資料欄名稱必須與 BigQuery 來源資料表中對應的資料欄名稱完全一致。X 表示表格可建立多個資料欄。名稱也必須與 BigQuery 資料欄的大小寫完全一致。如果 BigQuery 資料欄名稱包含大寫字母 (例如 employeeID)，AlloyDB 識別碼必須以雙引號括住 (例如 "employeeID")，才能保留大小寫混合或大寫字母。
- DATA_TYPE：資料欄的資料類型。
- BIGQUERY_SERVER_NAME：您建立的外部伺服器專屬 ID。
- BIGQUERY_PROJECT_ID：BigQuery 資料集所在的專案 ID。
- BIGQUERY_DATASET_NAME：資料表的 BigQuery 資料集名稱。
- BIGQUERY_TABLE_NAME：BigQuery 資料表的名稱。
建立外部資料表後，您就可以像查詢 AlloyDB 中的任何資料表一樣，查詢這個資料表。

匯入資料

如要將 BigQuery 資料或儲存在 BigQuery 中的 BigLake Iceberg 資料匯入 AlloyDB，請按照下列步驟操作：

找出現有資料來源，或建立內建 BigQuery 資料表或新的 Iceberg 受管理資料表。
使用 psql 執行下列指令，建立 local_table：
```
CREATE TABLE local_table AS (SELECT * from foreign_table);
```
這項指令會將 BigQuery 資料表複製到本機標準 AlloyDB 資料表。視應用程式工作流程而定，您可以設定 PostgreSQL pg_cron 擴充功能，定期重新整理 AlloyDB 資料表。

設定定期匯入資料的時間表

匯入 BigQuery 資料時，bigquery_fdw 會以外部資料表的形式連線至遠端資料表，讓您使用 CREATE TABLE ... AS (SELECT * FROM foreign_table) 將資料複製到本機 AlloyDB 儲存空間。

如要確保匯入的資料表為最新狀態，可以使用 pg_cron 擴充功能定期重新執行這項查詢，並依排程重新整理店面資料。

附註：這個方法會透過 bigquery_fdw 執行 SQL 查詢，定期重建 BigQuery 資料表的本機副本。如需自動化代管的背景資料同步功能，且不想手動維護週期性 SQL 指令碼或表格替換作業，請改用 alloydb_sync 擴充功能。詳情請參閱將 BigQuery 資料同步至 AlloyDB。

如要設定排程，定期將 BigQuery 資料或 BigLake Iceberg 資料匯入 AlloyDB，請按照下列步驟操作：

設定 bigquery_fdw 擴充功能。
在 AlloyDB 執行個體上啟用 pg_cron 擴充功能。詳情請參閱「支援的資料庫擴充功能」。
1. 將 alloydb.enable_pg_cron 旗標設為 on。詳情請參閱 alloydb.enable_pg_cron。
2. 將 cron.database_name 旗標設為安裝 bigquery_fdw 擴充功能的資料庫名稱，並在該資料庫中執行 SQL 查詢來重新整理資料。詳情請參閱「支援的資料庫標記」。
如要定期重新整理外部資料表的本機副本，請在安裝 bigquery_fdw 擴充功能的資料庫中執行下列指令：
```
CREATE EXTENSION pg_cron;
SELECT cron.schedule(JOB_NAME, SCHEDULE, 'CREATE TABLE IF NOT EXISTS local_table_copy AS (SELECT * FROM foreign_table); DROP TABLE IF EXISTS local_table; ALTER TABLE local_table_copy RENAME TO local_table;');
```
更改下列內容：
- JOB_NAME：工作名稱。
- SCHEDULE：工作排程。
詳情請參閱「什麼是 pg_cron？」。

資料類型對應關係

使用 bigquery_fdw 定義外部資料表時，請將 BigQuery 資料類型對應至適當的 PostgreSQL 類型。

下表列出 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`擴充功能。