使用互動式 SQL 翻譯器翻譯查詢

本文說明如何使用 BigQuery 互動式 SQL 翻譯工具，將查詢從不同的 SQL 方言翻譯成 GoogleSQL 查詢。互動式 SQL 翻譯器能讓您用更少的時間和心力，將工作負載遷移至 BigQuery。本文適用於熟悉 Google Cloud 控制台或 Google Cloud CLI 的使用者。

注意： 如要建構自訂軟體整合、自動化 CI/CD 管道或其他程式輔助工作流程，請參閱 BigQuery Migration API 指南。

您可以使用翻譯規則功能，自訂互動式 SQL 翻譯器翻譯 SQL 的方式。

如要查看這項 SQL 翻譯工具支援的 SQL 方言清單，請參閱「支援的 SQL 方言」。

如需支援的處理位置清單，請參閱「位置」。

事前準備

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

啟用 SQL 翻譯

啟用必要的 API，並取得使用 BigQuery SQL 翻譯工具所需的權限。詳情請參閱「啟用 SQL 翻譯」。

所需權限

如要取得使用互動式翻譯工具、Translation API 或批次 SQL 翻譯工具建立翻譯工作所需的權限，請要求管理員授予您 parent 資源的下列 IAM 角色：

• 查看及監控遷移工作：MigrationWorkflow 檢視者 (roles/bigquerymigration.viewer)
• 提交遷移工作：MigrationWorkflow 編輯者 (roles/bigquerymigration.editor)
• 存取 Cloud Storage bucket 以取得輸入內容和檔案：Storage 物件管理員 (roles/storage.objectAdmin) - 位於來源和目的地 Cloud Storage bucket。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備所需權限，可透過互動式翻譯工具、Translation API 或批次 SQL 翻譯工具建立翻譯工作。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要使用互動式翻譯工具、Translation API 或批次 SQL 翻譯工具建立翻譯工作，必須具備下列權限：

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

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

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

將 SQL 從來源方言轉譯為 BigQuery 時，某些函式可能沒有直接對應的函式。為解決這個問題，BigQuery 遷移服務 (和更廣泛的 BigQuery 社群) 提供輔助 user-defined function (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 翻譯器僅適用於特定處理位置。詳情請參閱「位置」。

Gemini 翻譯設定僅適用於特定處理位置。詳情請參閱「Google 模型端點位置」

將查詢轉譯為 GoogleSQL

您可以使用 Google Cloud 控制台或 Google Cloud CLI 翻譯查詢。

控制台

請按照下列步驟，將查詢翻譯成 GoogleSQL：

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

   前往「BigQuery」

2. 在「編輯器」窗格中，依序點選「工具」>「翻譯設定」。

3. 在「Source dialect」(來源方言) 中，選取要翻譯的 SQL 方言。

4. 選用。在「Processing location」(處理位置) 中，選取要執行翻譯工作的位置。舉例來說，如果您位於歐洲，且不希望資料跨越任何位置限制範圍，請選取 eu 區域。

5. 按一下 [儲存]。

6. 在「Editor」(編輯器) 窗格中，依序點選「Tools」(工具) >「Enable SQL translation」(啟用 SQL 翻譯)。

   「Editor」窗格會分成兩個窗格。

7. 在左側窗格中，輸入要翻譯的查詢。

8. 按一下「Translate」(翻譯)。

   BigQuery 會將查詢轉譯為 GoogleSQL，並顯示在右側窗格中。舉例來說，下列螢幕截圖顯示翻譯後的 Teradata SQL：

   

9. 選用：如要執行翻譯後的 GoogleSQL 查詢，請按一下「執行」。

10. 選用步驟：如要返回 SQL 編輯器，請依序點選「More」(更多) >「Disable SQL translation」(停用 SQL 翻譯)。

    「Editor」(編輯器) 窗格會恢復為單一窗格。

gcloud

預覽

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

如要使用 Google Cloud CLI 翻譯查詢，請執行 gcloud alpha bq translation translate 指令：

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE

更改下列內容：

• SOURCE_DIALECT：要翻譯的 SQL 方言，例如 teradata。如需支援的值，請參閱「支援的 SQL 方言」。
• TARGET_DIALECT：查詢要翻譯成的方言。例如：bigquery。
• LOCATION：要執行翻譯工作的位置。舉例來說，如果您位於歐洲，且不希望資料跨越任何位置限制範圍，請指定 eu 區域。
• INPUT_FILE：本機檔案，包含要翻譯的查詢。

指令會將翻譯後的查詢輸出至 gcloud CLI。如要改為將翻譯後的查詢寫入檔案，請新增 --output-file 旗標。

如要翻譯查詢而不建立檔案，請透過標準輸入內容傳送查詢，並省略 --input-file 旗標：

echo 'SELECT 1;' | gcloud alpha bq translation translate \
  --source-dialect=teradata \
  --target-dialect=bigquery \
  --location=us

如要套用原本會在「Translation settings」(翻譯設定) 中設定的自訂項目，請使用下列旗標：

• --translation-config-files：以半形逗號分隔的設定 YAML 檔案清單。檔案名稱結尾必須是 .config.yaml。
• --metadata-gcs-uri：中繼資料 ZIP 檔案的 Cloud Storage URI。
• --explanation-output-file：本機檔案，用於接收 Gemini 生成的翻譯說明。

搭配使用 Gemini 和互動式 SQL 翻譯器

您可以設定互動式 SQL 翻譯器，調整翻譯來源 SQL 的方式。您可以透過 YAML 設定檔提供自己的規則，供 Gemini 使用，或提供包含 SQL 物件中繼資料或物件對應資訊的設定 YAML 檔案。

建立及套用 Gemini 強化翻譯規則

注意： 如要取得支援及提供預先發布版功能的意見回饋，請傳送電子郵件至 [e-mail]。

您可以建立翻譯規則，自訂互動式 SQL 翻譯器翻譯 SQL 的方式。互動式 SQL 轉譯器會根據您指派的 Gemini 強化 SQL 轉譯規則調整轉譯內容，讓您依據遷移需求自訂轉譯結果。

如要建立 Gemini 輔助 SQL 轉譯規則，您可以在控制台建立，也可以建立設定 YAML 檔案，並上傳至 Cloud Storage。

控制台

如要為輸入 SQL 建立 Gemini 強化 SQL 轉譯規則，請在查詢編輯器中編寫輸入 SQL 查詢，然後依序點選「ASSIST」(協助) >「Customize」(自訂)。(預先發布版)

同樣地，如要為輸出 SQL 建立 Gemini 輔助 SQL 翻譯規則，請執行互動式翻譯，然後依序點選「ASSIST」(協助) >「Customize this translation」(自訂這項翻譯)。

「自訂」選單出現後，請繼續執行下列步驟。

1. 使用下列其中一或兩種提示建立轉譯規則：

   • 在「Find and replace a pattern」(尋找並取代模式) 提示中，在「Replace」(取代) 欄位指定要取代的 SQL 模式，並在「With」(取代為) 欄位指定要取代的 SQL 模式。

     SQL 模式可包含 SQL 指令碼中的任意數量的陳述式、子句或函式。使用這則提示建立規則時，Gemini 強化 SQL 轉譯功能會找出 SQL 查詢中該 SQL 模式的所有執行個體，並動態替換成其他 SQL 模式。舉例來說，您可以使用這則提示建立規則，將所有 months_between (X,Y) 替換為 date_diff(X,Y,MONTH)。

   • 在「Describe a change to the output」(說明輸出內容的變更) 欄位中，以自然語言輸入 SQL 翻譯輸出內容的變更。

     使用這則提示建立規則時，Gemini 強化版 SQL 轉譯功能會辨識要求，並對 SQL 查詢進行指定變更。

2. 按一下「預覽」。

3. 在「Suggestions generated by Gemini」(Gemini 生成的建議) 對話方塊中，查看 Gemini 強化版 SQL 翻譯功能根據規則對 SQL 查詢所做的變更。

   

4. 選用：如要新增這項規則，以便用於日後的翻譯作業，請勾選「Save this prompt...」(儲存這項提示...) 核取方塊。

   規則會儲存在預設設定 YAML 檔案或 __default.ai_config.yaml 中。這個設定 YAML 檔案會儲存至 Cloud Storage 資料夾，如轉譯設定的「Translation Configuration Source Location」(轉譯設定來源位置) 欄位所指定。如果尚未設定轉譯設定來源位置，系統會顯示資料夾瀏覽器，讓您選取位置。設定 YAML 檔案須遵守設定檔大小限制。

5. 如要將建議的變更套用至 SQL 查詢，請按一下「Apply」(套用)。

YAML

如要建立 Gemini 強化版 SQL 轉譯規則，您可以建立以 Gemini 為基礎的設定 YAML 檔案，並上傳至 Cloud Storage。詳情請參閱「建立 Gemini 設定 YAML 檔案」。

上傳 Gemini 強化 SQL 轉譯規則至 Cloud Storage 後，請按照下列步驟套用規則：

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

   前往「BigQuery」

2. 在查詢編輯器中，依序點選「工具」>「翻譯設定」。

3. 在「Translation Configuration Source Location」(翻譯設定來源位置) 欄位中，指定儲存在 Cloud Storage 資料夾中的 Gemini 型 YAML 檔案路徑。

4. 按一下 [儲存]。

   儲存後，請執行互動式翻譯。互動式翻譯工具會根據設定 YAML 檔案 (如有) 中的規則，建議翻譯變更。

如果 Gemini 根據規則對輸入內容提供建議，系統會顯示「Preview suggested changes」(預覽建議的變更) 對話方塊，並顯示可能對翻譯輸入內容進行的變更。(預覽)

如果 Gemini 可根據規則提供輸出內容建議，程式碼編輯器會顯示通知橫幅。如要查看及套用這些建議，請按照下列步驟操作：

1. 在程式碼編輯器任一側，依序點選「Assist」>「View suggestions」，即可重新查看對應查詢的建議變更。

   

2. 在「Suggestions generated by Gemini」(Gemini 生成的建議) 對話方塊中，查看 Gemini 根據轉譯規則對 SQL 查詢所做的變更。

3. 如要將建議變更套用至翻譯輸出內容，請按一下「套用」。

更新 Gemini 輔助設定 YAML 檔案

如要更新現有的 YAML 設定檔，請按照下列步驟操作：

1. 在「Suggestions generated in Gemini」(Gemini 生成的建議) 對話方塊中，按一下「View Gemini rule config file」(查看 Gemini 規則設定檔)。

2. 設定編輯器顯示後，選取要編輯的設定 YAML 檔案。

3. 進行變更，然後按一下「儲存」。

4. 按一下「完成」，關閉 YAML 編輯器。

5. 執行互動式轉譯，套用更新後的規則。

說明翻譯內容

預覽

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

注意： 透過 Gemini 強化 SQL 翻譯功能，您可以使用 Gemini 模型生成指令碼的文字說明。Gemini 輔助 SQL 翻譯功能提供免付費的 Gemini 用量額度。這個用量足以應付大多數遷移專案。如要申請提高這項限制，或針對這項預先發布版功能尋求支援及提供意見回饋，請傳送電子郵件至 [e-mail]。

執行互動式翻譯後，您可以要求 Gemini 生成文字說明。生成的文字包含翻譯 SQL 查詢的摘要。Gemini 也會找出來源 SQL 查詢和轉譯 GoogleSQL 查詢之間的轉譯差異和不一致之處。

如要取得 Gemini 生成的 SQL 翻譯說明，請按照下列步驟操作：

1. 如要建立 Gemini 生成的 SQL 翻譯說明，請依序點選「Assist」(協助) 和「Explain this translation」(說明這項翻譯)。

   

使用批次翻譯設定 ID 翻譯

您可以提供批次翻譯設定 ID，執行與批次翻譯工作採用相同翻譯設定的互動式查詢。

1. 在查詢編輯器中，依序點選「工具」>「翻譯設定」。

2. 在「Translation Configuration ID」(翻譯設定 ID) 欄位中，提供批次翻譯設定 ID，套用已完成 BigQuery 批次遷移工作的相同翻譯設定。

   如要找出工作的批次翻譯設定 ID，請在「SQL translation」(SQL 翻譯) 頁面中選取批次翻譯工作，然後按一下「Translation Configuration」(翻譯設定) 分頁標籤。批次翻譯設定 ID 會列為「Resource name」(資源名稱)。

3. 按一下 [儲存]。

使用其他設定翻譯

您可以指定儲存在 Cloud Storage 資料夾中的設定 YAML 檔案，透過其他轉譯設定執行互動式查詢。翻譯設定可能包含來源資料庫的 SQL 物件中繼資料或物件對應資訊，可提升翻譯品質。舉例來說，您可以加入來源資料庫的 DDL 資訊或結構定義，提升互動式 SQL 翻譯品質。

如要提供翻譯設定來源檔案的位置，藉此指定翻譯設定，請按照下列步驟操作：

1. 在查詢編輯器中，依序點選「工具」>「翻譯設定」。

2. 在「Translation Configuration Source Location」(轉譯設定來源位置) 欄位中，指定 Cloud Storage 資料夾中儲存的轉譯設定檔路徑。

   BigQuery 互動式 SQL 翻譯器支援包含翻譯中繼資料和物件名稱對應的中繼資料 ZIP 檔案。如要瞭解如何將檔案上傳至 Cloud Storage，請參閱「從檔案系統上傳物件」。

3. 按一下 [儲存]。

設定檔大小限制

使用 BigQuery 互動式 SQL 轉譯器搭配轉譯設定檔時，壓縮的中繼資料檔案或 YAML 設定檔必須小於 50 MB。如果檔案大小超過 50 MB，互動式翻譯工具會在翻譯期間略過該設定檔，並產生類似下列的錯誤訊息：

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

如要縮減中繼資料檔案大小，其中一個方法是使用 --database 或 --schema 旗標，只擷取與翻譯輸入查詢相關的資料庫或結構定義中繼資料。如要進一步瞭解如何在產生中繼資料檔案時使用這些旗標，請參閱「全域旗標」。

排解翻譯錯誤

以下各節說明使用互動式 SQL 翻譯器時常見的錯誤。

RelationNotFound或AttributeNotFound翻譯問題

使用互動式 SQL 翻譯器翻譯查詢後，您可能會遇到翻譯失敗，並出現 RelationNotFound 或 AttributeNotFound 錯誤。

如要找出失敗的翻譯，請前往 Google Cloud 控制台中的 BigQuery「Translation details」(翻譯詳細資料) 頁面，然後開啟「Log Messages」(記錄訊息) 分頁。

為確保翻譯結果最準確，您可以在查詢前，先輸入查詢中使用的任何資料表的資料定義語言 (DDL) 陳述式。舉例來說，如要翻譯 Amazon Redshift 查詢 select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;，請在互動式 SQL 翻譯器中輸入下列 SQL 陳述式：

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

使用 Gemini 修正翻譯問題

預覽

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

注意： 如要針對這項功能提供意見或尋求支援，請傳送電子郵件至 [e-mail]。

如要修正失敗的翻譯工作，並解決 RelationNotFound 或 AttributeNotFound 錯誤，您也可以使用 Gemini 解決這些問題：

1. 在 Google Cloud 控制台的 BigQuery 中，前往「Translation details」(翻譯詳細資料) 頁面，然後開啟「Log Messages」(記錄訊息) 分頁。
2. 在「類別」欄中，按一下含有「RelationNotFound」或「AttributeNotFound」訊息的查詢。
3. 按一下「建議修正」。
4. 按一下「套用」。
5. 如要重新翻譯查詢，請點選「Translate」(翻譯)。

定價

使用互動式 SQL 翻譯器無須付費。不過，用於儲存輸入和輸出檔案的儲存空間會產生一般費用。詳情請參閱儲存空間定價。

後續步驟

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

• 遷移作業總覽
• 遷移評估
• 結構定義與資料移轉總覽
• 批次 SQL 翻譯
• 資料管道
• 資料安全性與管理
• 資料驗證工具