使用批次 SQL 翻譯器遷移程式碼

本文件說明如何使用 BigQuery 中的批次 SQL 翻譯器，將以其他 SQL 方言編寫的指令碼翻譯成 GoogleSQL 查詢。本文件適用於熟悉 Google Cloud 控制台的使用者。

事前準備

提交翻譯工作前，請先完成下列步驟：

1. 請確認您具備所有必要權限。
2. 啟用 BigQuery Migration API。
3. 收集含有待翻譯 SQL 指令碼和查詢的來源檔案。
4. (選用步驟) 建立中繼資料檔案，提升翻譯準確度。
5. (選用步驟) 決定是否需要將來源檔案中的 SQL 物件名稱對應至 BigQuery 中的新名稱。視需要決定要使用的名稱對應規則。
6. 決定要使用哪種方法提交翻譯工作。
7. 將來源檔案上傳至 Cloud Storage。

所需權限

您必須具備下列專案權限，才能啟用 BigQuery 遷移服務：

• resourcemanager.projects.get
• serviceusage.services.enable
• serviceusage.services.get

您必須具備下列專案權限，才能存取及使用 BigQuery 遷移服務：

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get
• bigquerymigration.workflows.list
• bigquerymigration.workflows.delete
• bigquerymigration.subtasks.get

• bigquerymigration.subtasks.list

  或者，您也可以使用下列角色取得相同權限：

  • bigquerymigration.viewer - 唯讀存取權。
  • bigquerymigration.editor - 讀取/寫入權限。

如要存取輸入和輸出檔案的 Cloud Storage 值區，請按照下列步驟操作：

• 來源 Cloud Storage 值區的 storage.objects.get。
• 來源 Cloud Storage 值區的 storage.objects.list。
• storage.objects.create 在目標 Cloud Storage 值區中。

您可以透過下列角色取得上述所有必要的 Cloud Storage 權限：

• roles/storage.objectAdmin
• roles/storage.admin

啟用 BigQuery Migration API

如果您的 Google Cloud CLI 專案是在 2022 年 2 月 15 日前建立，請按照下列步驟啟用 BigQuery Migration API：

1. 前往 Google Cloud 控制台的「BigQuery Migration API」頁面。

   前往 BigQuery Migration API

2. 按一下「啟用」。

收集來源檔案

來源檔案必須是包含來源方言有效 SQL 的文字檔。來源檔案也可以包含註解。請盡可能使用任何可用的方法，確保 SQL 有效。

建立中繼資料檔案

為協助服務產生更準確的翻譯結果，建議您提供中繼資料檔案。不過，這並非必要條件。

您可以使用 dwh-migration-dumper 指令列擷取工具產生中繼資料資訊，也可以提供自己的中繼資料檔案。準備好中繼資料檔案後，您可以將這些檔案與來源檔案一併納入翻譯來源資料夾中。翻譯器會自動偵測並利用這些詞彙來翻譯來源檔案，您不需要設定任何額外設定即可啟用這項功能。

如要使用 dwh-migration-dumper 工具產生中繼資料資訊，請參閱「產生翻譯的中繼資料」。

如要提供自己的中繼資料，請收集來源系統中 SQL 物件的資料定義語言 (DDL) 陳述式，並儲存在個別的文字檔中。

決定如何提交翻譯工作

提交批次翻譯工作有三種方式：

• Batch 翻譯客戶端：變更設定檔中的設定來設定工作，然後使用指令列提交工作。這個方法不需要您手動將來源檔案上傳至 Cloud Storage。在翻譯工作處理期間，用戶端仍會使用 Cloud Storage 儲存檔案。

  舊版批次翻譯用戶端是開放原始碼 Python 用戶端，可讓您翻譯本機上的來源檔案，並將翻譯檔案輸出至本機目錄。您可以變更設定檔中的幾項設定，為用戶端進行基本設定。您也可以視需要設定用戶端，以處理更複雜的工作，例如巨集取代，以及翻譯輸入內容和輸出內容的前置和後置處理。詳情請參閱批次翻譯用戶端的 說明檔。

• Google Cloud 控制台：使用使用者介面設定及提交工作。您必須將來源檔案上傳至 Cloud Storage，才能使用這種方法。

建立 YAML 設定檔

您可以選擇建立並使用設定 YAML 設定檔，自訂批次翻譯作業。這些檔案可用於以各種方式轉換翻譯輸出內容。舉例來說，您可以建立設定 YAML 檔案，在轉譯期間變更 SQL 物件的大小寫。

如果您想使用 Google Cloud 控制台或 BigQuery Migration API 進行批次翻譯工作，可以將設定 YAML 檔案上傳至含有來源檔案的 Cloud Storage 值區。

如果要使用批次翻譯用戶端，可以將設定 YAML 檔案放在本機翻譯輸入資料夾中。

將輸入檔案上傳至 Cloud Storage

如果您想使用 Google Cloud 主控台或 BigQuery Migration API 執行轉譯工作，必須將含有要轉譯的查詢和指令碼的原始檔案上傳至 Cloud Storage。您也可以將任何中繼資料檔案或設定 YAML 檔案上傳至含有原始檔案的同一 Cloud Storage 值區。如要進一步瞭解如何建立值區及將檔案上傳至 Cloud Storage，請參閱「建立值區」和「從檔案系統上傳物件」相關說明。

支援的 SQL 方言

批次 SQL 翻譯器是 BigQuery 遷移服務的一部分。批次 SQL 翻譯器可將下列 SQL 方言翻譯為 GoogleSQL：

• Amazon Redshift SQL
• Apache HiveQL 和 Beeline CLI
• IBM Netezza SQL 和 NZPLSQL
• Teradata 和 Teradata Vantage
  • SQL
  • 基本 Teradata 查詢 (BTEQ)
  • Teradata Parallel Transport (TPT)

此外，預先發布版支援翻譯下列 SQL 方言：

• Apache Spark SQL
• Azure Synapse T-SQL
• Greenplum SQL
• IBM DB2 SQL
• MySQL SQL
• Oracle SQL、PL/SQL、Exadata
• PostgreSQL SQL
• Trino 或 PrestoSQL
• Snowflake SQL
• SQL Server T-SQL
• SQLite
• Vertica SQL

使用輔助 UDF 處理不支援的 SQL 函式

將 SQL 從來源方言轉譯至 BigQuery 時，某些函式可能沒有直接對應的函式。為解決這個問題，BigQuery 遷移服務 (以及更廣泛的 BigQuery 社群) 提供輔助使用者定義函式 (UDF)，可複製這些不支援的來源方言函式的行為。

這些 UDF 通常會出現在 bqutil 公開資料集，讓經過翻譯的查詢最初以 bqutil.<dataset>.<function>() 格式參照這些 UDF。例如：bqutil.fn.cw_count()。

正式環境的重要注意事項：

雖然 bqutil 可讓您輕鬆存取這些輔助 UDF，用於初始轉譯和測試，但不建議直接依賴 bqutil 處理實際工作負載，原因如下：

1. 版本控制：bqutil 專案會代管這些 UDF 的最新版本，因此定義可能會隨時間變更。如果 UDF 邏輯更新，直接依賴 bqutil 可能會導致意外行為或破壞實際工作環境查詢。
2. 依附元件隔離：將 UDF 部署至專案，可將正式環境與外部變更隔離。
3. 自訂：您可能需要修改或最佳化這些 UDF，以便更符合特定業務邏輯或成效需求。只有在這些資源位於您自己的專案中時，才能使用這項功能。
4. 安全性和治理：貴機構的安全性政策可能會限制直接存取 bqutil 等公開資料集，以便處理實際工作環境中的資料。將 UDF 複製到受控環境，即可符合這類政策。

將輔助 UDF 部署至專案：

為了確保可靠且穩定的實際工作環境使用體驗，您應將這些輔助 UDF 部署至專屬專案和資料集。這樣一來，您就能完全掌控版本、自訂選項和存取權。如需部署這些 UDF 的詳細操作說明，請參閱 GitHub 上的 UDF 部署指南。本指南提供必要的指令碼和步驟，協助您將 UDF 複製到環境中。

位置

批次 SQL 翻譯器可在下列處理位置使用：

	區域說明	區域名稱	詳細資料
亞太地區
	德里	asia-south2
	香港	asia-east2
	雅加達	asia-southeast2
	墨爾本	australia-southeast2
	孟買	asia-south1
	大阪	asia-northeast2
	首爾	asia-northeast3
	新加坡	asia-southeast1
	雪梨	australia-southeast1
	台灣	asia-east1
	東京	asia-northeast1
歐洲
	比利時	europe-west1	二氧化碳排放量低2
	柏林	europe-west10	二氧化碳排放量低2
	歐盟多個區域	eu
	芬蘭	europe-north1	低二氧化碳
	法蘭克福	europe-west3	二氧化碳排放量低2
	倫敦	europe-west2	二氧化碳排放量低2
	馬德里	europe-southwest1	二氧化碳排放量低2
	米蘭	europe-west8
	荷蘭	europe-west4	二氧化碳排放量低
	巴黎	europe-west9	二氧化碳排放量低2
	斯德哥爾摩	europe-north2	低二氧化碳
	杜林	europe-west12
	華沙	europe-central2
	蘇黎世	europe-west6	二氧化碳排放量低
美洲
	俄亥俄州哥倫布	us-east5
	達拉斯	us-south1	二氧化碳排放量低2
	愛荷華州	us-central1	二氧化碳排放量低2
	拉斯維加斯	us-west4
	洛杉磯	us-west2
	墨西哥	northamerica-south1
	北維吉尼亞州	us-east4
	奧勒岡州	us-west1	二氧化碳排放量低2
	魁北克	northamerica-northeast1	二氧化碳排放量低2
	聖保羅	southamerica-east1	二氧化碳排放量低
	鹽湖城	us-west3
	聖地亞哥	southamerica-west1	二氧化碳排放量低2
	南卡羅來納州	us-east1
	多倫多	northamerica-northeast2	二氧化碳排放量低2
	美國 (多個區域)	us
非洲
	約翰尼斯堡	africa-south1
MiddleEast
	達曼	me-central2
	杜哈	me-central1
	以色列	me-west1

提交翻譯工作

請按照下列步驟啟動翻譯工作、查看進度，並查看結果。

探索翻譯輸出內容

執行翻譯工作後，您可以在 Google Cloud 控制台中查看工作相關資訊。如果您使用 Google Cloud 主控台執行工作，可以在指定的 Cloud Storage 目的地值區中查看工作結果。如果您使用批次翻譯用戶端執行工作，可以在指定的輸出目錄中查看工作結果。批次 SQL 翻譯器會將下列檔案輸出至指定的目標：

• 已翻譯的檔案。
• CSV 格式的翻譯摘要報告。
• 以 JSON 格式呈現的已使用輸出名稱對應項目。
• AI 建議檔案。

Google Cloud 控制台輸出內容

如要查看翻譯工作詳細資料，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中，找出您要查看翻譯詳細資料的工作。然後按一下翻譯工作名稱。 您可以查看桑基圖示化資料，瞭解工作整體品質、輸入程式碼列數量 (不含空白列和註解)，以及在翻譯過程中發生的問題清單。您應優先處理從左到右的修正項目。初期的問題可能會導致後續階段出現其他問題。

4. 將游標懸停在錯誤或警告列上，並查看建議，以便決定如何修正翻譯工作。

5. 選取「記錄摘要」分頁，即可查看翻譯問題的摘要，包括問題類別、建議的動作，以及每個問題發生的頻率。您可以按一下 Sankey 圖示化條，篩選問題。您也可以選取問題類別，查看與該問題類別相關的記錄訊息。

6. 選取「記錄訊息」分頁，即可進一步瞭解每個翻譯問題的詳細資料，包括問題類別、具體問題訊息，以及發生問題的檔案連結。您可以按一下 Sankey 圖示化列，篩選問題。您可以在「Log Message」分頁中選取問題，開啟「Code」分頁，並在其中查看輸入和輸出檔案 (如有)。

7. 按一下「工作詳細資料」分頁標籤，查看翻譯工作設定的詳細資料。

摘要報告

摘要報告是 CSV 檔案，其中包含表格，列出翻譯作業期間遇到的所有警告和錯誤訊息。

如要在 Google Cloud 主控台中查看摘要檔案，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中找出你感興趣的工作，然後按一下工作名稱或點選「更多選項」>「顯示詳細資料」。

4. 在「工作詳細資料」分頁標籤的「翻譯報表」部分，按一下「translation_report.csv」。

5. 在「Object details」頁面中，按一下「Authenticated URL」列中的值，即可在瀏覽器中查看檔案。

下表說明摘要檔案的欄位：

「Code」分頁

您可以透過「code」分頁，查看特定翻譯工作的輸入和輸出檔案相關詳細資訊。在「code」分頁中，您可以檢查翻譯工作中使用的檔案、並逐一查看輸入檔案與翻譯結果，以便找出任何不正確之處，以及查看工作中特定檔案的記錄摘要和訊息。

如要存取程式碼分頁，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中找出你感興趣的工作，然後按一下工作名稱或點選「更多選項」>「顯示詳細資料」。

4. 選取「Code」分頁。「程式碼」分頁包含下列面板：

   

   • 檔案總管：包含用於翻譯的所有 SQL 檔案。按一下檔案即可查看翻譯輸入內容和輸出內容，以及翻譯內容中的任何翻譯問題。
   • Gemini 強化輸入內容：由翻譯引擎翻譯的輸入 SQL。如果您已在 Gemini 設定中為來源 SQL 指定 Gemini 自訂化規則，轉譯器會先轉換原始輸入內容，然後再轉譯經 Gemini 強化的輸入內容。如要查看原始輸入內容，請點選「查看原始輸入內容」。
   • 翻譯輸出內容：翻譯結果。如果您在 Gemini 設定中為目標 SQL 指定 Gemini 自訂規則，系統就會將轉換套用至轉譯結果，並以 Gemini 強化的輸出格式呈現。如果有 Gemini 強化的輸出內容，您可以點選「Gemini 建議」按鈕，查看 Gemini 強化的輸出內容。

5. 選用：如要在 BigQuery 互動式 SQL 翻譯器中查看輸入檔案及其輸出檔案，請按一下「編輯」。您可以編輯檔案，並將輸出檔案儲存回 Cloud Storage。

「設定」分頁

您可以在「設定」分頁中新增、重新命名、查看或編輯設定 YAML 檔案。架構資源管理工具會顯示支援的設定類型說明文件，協助您編寫設定 YAML 檔案。編輯設定 YAML 檔案後，您可以重新執行工作來使用新設定。

如要存取設定分頁，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中找出你感興趣的工作，然後按一下工作名稱或點選「更多選項」>「顯示詳細資料」。

4. 在「翻譯詳細資料」視窗中，按一下「設定」分頁標籤。

如要新增設定檔，請按照下列步驟操作：

1. 依序按一下「more_vert」more_vert「更多選項」>「建立設定 YAML 檔案」。
2. 面板隨即顯示，您可以選擇新設定 YAML 檔案的類型、位置和名稱。
3. 按一下 [建立]。

如要編輯現有的設定檔，請按照下列步驟操作：

1. 按一下設定 YAML 檔案。
2. 編輯檔案，然後按一下「儲存」。
3. 點選「重新執行」，即可執行使用已編輯的設定 YAML 檔案的新轉譯工作。

如要重新命名現有的設定檔，請依序點選 more_vert「更多選項」>「重新命名」。

已使用的輸出名稱對應檔案

這個 JSON 檔案包含翻譯工作所使用的輸出名稱對應規則。由於名稱對應規則有衝突，或是在翻譯期間找出的 SQL 物件缺少名稱對應規則，因此這個檔案中的規則可能與您為翻譯工作指定的輸出名稱對應規則不同。請查看這個檔案，判斷是否需要修正名稱對應規則。如果是，請建立新的輸出名稱對應規則，解決您發現的任何問題，然後執行新的翻譯工作。

已翻譯的檔案

系統會在目的地路徑中，為每個來源檔案產生對應的輸出檔案。輸出檔案包含翻譯後的查詢。

使用互動式 SQL 翻譯器對批次翻譯的 SQL 查詢進行偵錯

您可以使用 BigQuery 互動式 SQL 翻譯器，使用與來源資料庫相同的結構描述或物件對應資訊，查看或偵錯 SQL 查詢。完成批次翻譯工作後，BigQuery 會產生翻譯設定 ID，其中包含工作中繼資料、物件對應或結構定義搜尋路徑的相關資訊 (視查詢而定)。您可以使用互動式 SQL 翻譯器搭配批次轉譯設定 ID，以指定的設定執行 SQL 查詢。

如要使用批次翻譯設定 ID 啟動互動式 SQL 翻譯，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中找出您有興趣的工作，然後依序點選 more_vert「更多選項」>「開啟互動式翻譯」。

   BigQuery 互動式 SQL 翻譯器現在會開啟對應的批次翻譯設定 ID。如要查看互動式翻譯的翻譯設定 ID，請在互動式 SQL 翻譯器中依序按一下「More」>「Translation settings」。

如要在互動式 SQL 翻譯器中對批次翻譯檔案進行偵錯，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在導覽選單中，按一下「SQL 翻譯」。

3. 在翻譯工作清單中找出你感興趣的工作，然後按一下工作名稱或點選「更多選項」>「顯示詳細資料」。

4. 在「Translation details」視窗中，按一下「Code」分頁標籤。

5. 在檔案總管中，按一下檔案名稱即可開啟檔案。

6. 按一下輸出檔案名稱旁的「編輯」，即可在互動式 SQL 翻譯器中開啟檔案 (預覽)。

   您會看到輸入和輸出檔案在互動式 SQL 翻譯器中填入，且現在使用對應的批次轉譯設定 ID。

7. 如要將已編輯的輸出檔案儲存回 Cloud Storage，請在互動式 SQL 翻譯器中依序點選「Save」>「Save To GCS」。

限制

轉譯器無法從 SQL 以外的語言轉譯使用者定義函式 (UDF)，因為它無法剖析這些函式，以便判斷其輸入和輸出資料類型。這會導致參照這些 UDF 的 SQL 陳述式翻譯結果不準確。為確保在轉譯期間能正確參照非 SQL UDF，請使用有效的 SQL 建立具有相同簽名的預留位置 UDF。

舉例來說，假設您有一個以 C 編寫的 UDF，用於計算兩個整數的總和。為確保參照此 UDF 的 SQL 陳述式正確轉譯，請建立與 C UDF 共用相同簽名的預留位置 SQL UDF，如以下範例所示：

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

請將這個預留位置 UDF 儲存至文字檔，並將該檔案納入翻譯工作的其中一個來源檔案。這可讓翻譯器學習 UDF 定義，並找出預期的輸入和輸出資料類型。

配額與限制

• 適用 BigQuery Migration API 配額。
• 每個專案最多只能有 10 個有效的翻譯工作。
• 雖然來源和中繼資料檔案的總數沒有硬性限制，但為了提升效能，建議您將檔案數量控制在 1000 以下。

排解翻譯錯誤

RelationNotFound 或 AttributeNotFound 翻譯問題

翻譯服務最適合搭配中繼資料 DDL 使用。如果找不到 SQL 物件定義，轉譯引擎會提出 RelationNotFound 或 AttributeNotFound 問題。建議您使用中繼資料擷取器產生中繼資料套件，確保所有物件定義都存在。建議您先新增中繼資料，這是解決大多數翻譯錯誤的第一步，因為這通常可以修正許多因缺少中繼資料而間接造成的其他錯誤。

詳情請參閱「產生翻譯和評估的中繼資料」。

定價

使用批次 SQL 翻譯器不需要支付費用。不過，用於儲存輸入和輸出檔案的儲存空間會產生一般費用。詳情請參閱「儲存空間定價」。

後續步驟

進一步瞭解資料倉儲遷移作業的下列步驟：

• 遷移作業總覽
• 遷移評估
• 結構定義與資料移轉總覽
• 資料管道
• 互動式 SQL 翻譯
• 資安與資管
• 資料驗證工具