疑難排解遷移問題

本文說明如何排解將資料倉儲 (例如 Teradata、Amazon Redshift、Oracle 或 Apache Hive) 遷移至 BigQuery 時的常見問題，包括遷移評估、互動式和批次 SQL 翻譯，以及使用 dwh-migration-dumper 指令列擷取工具產生中繼資料時的問題。

如要檢查已遷移查詢和工作的執行詳細資料、錯誤代碼和運算單元用量，您也可以查詢 INFORMATION_SCHEMA.JOBS 檢視表。

遷移評估

以下各節將說明將資料倉儲遷移至 BigQuery 時的常見問題和疑難排解技巧。

dwh-migration-dumper 個工具錯誤

如要排解中繼資料或查詢記錄擷取期間，dwh-migration-dumper工具終端機 輸出內容中發生的錯誤和警告，請參閱產生中繼資料疑難排解。

Hive 遷移錯誤

以下各節說明您在規劃將資料倉儲從 Hive 遷移至 BigQuery 時，可能遇到的常見問題。

hadoop-migration-assessment 查詢記錄擷取記錄掛鉤會將偵錯記錄訊息寫入 hive-server2 記錄。如果遇到任何問題，請查看記錄掛鉤的偵錯記錄檔，其中包含 MigrationAssessmentLoggingHook 字串。

處理 ClassNotFoundException 錯誤

如果 hive-server2 程序在查詢編譯期間找不到 com.google.cloud.bigquery.dwhassessment.hooks.MigrationAssessmentLoggingHook，就會發生這項錯誤。

請確認您已將記錄掛鉤 JAR 檔案新增至 Hive 叢集上的 auxlib 資料夾，或在 hive.aux.jars.path 屬性中指定 JAR 檔案的完整路徑，例如 file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar。

如果錯誤仍未解決，請按照下列步驟操作：

• 驗證 Cloudera (CDP 或 CDH) 上的 JAR 位置：在 Cloudera 環境中，輔助 JAR 屬性 (hive.aux.jars.path) 可能無法穩定載入根查詢編譯類別載入器。如要解決這個問題，請將記錄掛鉤 JAR 檔案直接複製到所有 HiveServer2 主機上的核心 Hive 程式庫目錄，例如 /opt/cloudera/parcels/CDH/lib/hive/lib/。

• 驗證設定範圍：如果您使用 Cloudera Manager，請務必將記錄掛鉤設定屬性 (例如 hive.exec.pre.hooks、hive.exec.post.hooks、hive.exec.failure.hooks 和 dwhassessment.hook.base-directory) 放在執行中的執行引擎設定程式碼片段中。舉例來說，如果叢集使用 Tez 執行，請將 XML 屬性新增至 Tez 進階設定程式碼片段 (安全閥) 欄位中的 Hive (適用於 hive-site.xml)，或新增至服務範圍的 Hive 安全閥，而不是新增至獨立的 HiveServer2 設定程式碼片段。儲存變更後，請重新啟動 Hive 服務，包括 HiveServer2 和 Hive Metastore 角色。

子資料夾未顯示在設定的資料夾中

這個問題可能是設定錯誤，或記錄勾點初始化期間發生問題所致。

在 hive-server2 偵錯記錄檔中搜尋下列記錄掛鉤訊息：

Unable to initialize logger, logging disabled

Log dir configuration key 'dwhassessment.hook.base-directory' is not set,
logging disabled.

Error while trying to set permission

查看問題詳情，看看是否有需要修正的地方。

資料夾中未顯示檔案

這個問題可能是事件處理期間或寫入檔案時發生問題所致。

在 hive-server2 偵錯記錄中搜尋下列記錄掛鉤訊息：

Failed to close writer for file

Got exception while processing event

Error writing record for query

查看問題詳細資料，確認是否需要修正任何內容來解決問題。

遺漏部分查詢事件

這個問題可能是記錄掛鉤執行緒佇列溢位所致。

在 hive-server2 偵錯記錄檔中搜尋下列記錄掛鉤訊息：

Writer queue is full. Ignoring event

如果看到這則訊息，建議您提高 dwhassessment.hook.queue.capacity 參數。

互動式 SQL 翻譯器

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

RelationNotFound 或 AttributeNotFound 翻譯問題

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

如要找出翻譯失敗的內容，請前往 Cloud de Confiance 控制台的 BigQuery「翻譯詳細資料」頁面，然後開啟「記錄訊息」分頁。

為確保翻譯結果最準確，您可以在查詢前，先輸入查詢中使用的任何資料表的資料定義語言 (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 修正翻譯問題

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

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

批次 SQL 翻譯器

以下各節說明使用批次 SQL 轉譯器時常見的錯誤。

RelationNotFound或AttributeNotFound翻譯問題

使用批次 SQL 翻譯器翻譯查詢後，您可能會遇到翻譯失敗的情況，並收到 RelationNotFound 或 AttributeNotFound 錯誤。

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

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

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

使用 Gemini 修正翻譯問題

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

1. 前往「翻譯詳細資料」頁面，然後開啟「記錄訊息」分頁。
2. 在「類別」欄中，按一下含有「RelationNotFound」或「AttributeNotFound」訊息的查詢。

3. 如要前往「Code」(程式碼) 分頁中包含錯誤的檔案和行，請按一下

   錯誤訊息。

4. 在「動作」欄中，按一下「建議修正」。

5. 選取下列其中一個選項：「套用」或「套用並重新執行」：

   • 如要將產生的結構定義檔案從輸出目錄複製到輸入目錄，請按一下「套用」。
   • 如要將產生的結構定義檔案從輸出目錄複製到輸入目錄，並開啟重新執行視窗，請按一下「Apply and rerun」。

產生翻譯和評估作業的中繼資料

以下各節說明 dwh-migration-dumper 工具的常見問題和疑難排解技巧。

「記憶體不足」錯誤

dwh-migration-dumper 工具終端機輸出內容中的 java.lang.OutOfMemoryError 錯誤，通常與處理擷取資料時記憶體不足有關。如要解決這個問題，請增加可用記憶體或減少處理執行緒數量。

如要提高記憶體上限，請匯出 JAVA_OPTS 環境變數：

export JAVA_OPTS="-Xmx4G"

set JAVA_OPTS="-Xmx4G"

您可以加入 --thread-pool-size 旗標值，減少處理執行緒數量 (預設為 32)。這個選項僅適用於 hiveql 和 redshift* 連接器：

dwh-migration-dumper --thread-pool-size=1

處理 WARN...Task failed 錯誤

有時您可能會在 dwh-migration-dumper 工具終端機輸出內容中看到 WARN [main] o.c.a.d.MetadataDumper [MetadataDumper.java:107] Task failed: … 錯誤。擷取工具會向來源系統提交多個查詢，並將每個查詢的輸出內容寫入各自的檔案。如果看到這個問題，表示其中一項查詢失敗。不過，即使其中一項查詢失敗，其他查詢仍會執行。如果看到多個 WARN 錯誤，請查看問題詳細資料，確認是否需要修正任何問題，才能正確執行查詢。舉例來說，如果您在執行擷取工具時指定的使用者沒有讀取所有中繼資料的權限，請改用具備正確權限的使用者再試一次。

ZIP 檔案毀損

如要驗證 dwh-migration-dumper 工具 ZIP 檔案，請下載 SHA256SUMS.txt 檔案，然後執行下列指令：

sha256sum --check SHA256SUMS.txt

(Get-FileHash RELEASE_ZIP_FILENAME).Hash -eq ((Get-Content SHA256SUMS.txt) -Split " ")[0]

Teradata 查詢記錄擷取作業緩慢

如要提升由 -Dteradata-logs.query-logs-table 和 -Dteradata-logs.sql-logs-table 旗標指定的聯結資料表效能，可以在 JOIN 條件中加入 DATE 類型的額外資料欄。這個資料欄必須在兩個資料表中定義，且必須是分區主索引的一部分。如要加入這個資料欄，請使用 -Dteradata-logs.log-date-column 旗標。

下列範例說明如何使用 -Dteradata-logs.log-date-column 旗標：

dwh-migration-dumper \
  -Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV \
  -Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl \
  -Dteradata-logs.log-date-column=ArchiveLogDate

dwh-migration-dumper `
  "-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV" `
  "-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl" `
  "-Dteradata-logs.log-date-column=ArchiveLogDate"

超過 Teradata 資料列大小限制

Teradata 15 版的資料列大小上限為 64 KB。如果超過上限，擷取工具會失敗，並顯示下列訊息：

[Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

如要解決這項錯誤，請將資料列限制擴大至 1 MB，或將資料列分割成多個資料列：

• 安裝並啟用 1 MB Perm 和 Response Rows 功能，以及目前的 TTU 軟體。詳情請參閱「Teradata Database Message 9804」。
• 使用 -Dteradata.metadata.max-text-length 和 -Dteradata-logs.max-sql-length 旗標，將長查詢文字分割成多個資料列。

下列指令說明如何使用 -Dteradata.metadata.max-text-length 旗標，將長查詢文字分割成多列，每列最多 10,000 個字元：

dwh-migration-dumper \
  --connector teradata \
  -Dteradata.metadata.max-text-length=10000

dwh-migration-dumper `
  --connector teradata `
  "-Dteradata.metadata.max-text-length=10000"

下列指令說明如何使用 -Dteradata-logs.max-sql-length 旗標，將長查詢文字分割成多個資料列，每個資料列最多 10,000 個字元：

dwh-migration-dumper \
  --connector teradata-logs \
  -Dteradata-logs.max-sql-length=10000

dwh-migration-dumper `
  --connector teradata-logs `
  "-Dteradata-logs.max-sql-length=10000"

Oracle 連線問題

在密碼或主機名稱無效等常見情況下，dwh-migration-dumper 工具會顯示有意義的錯誤訊息，說明根本問題。不過，在某些情況下，Oracle 伺服器傳回的錯誤訊息可能很籠統，難以調查。

其中一個問題是 IO Error: Got minus one from a read call。這項錯誤表示已建立與 Oracle 伺服器的連線，但伺服器拒絕接受用戶端並關閉連線。這類問題通常發生於伺服器只接受 TCPS 連線時。根據預設，dwh-migration-dumper 工具會使用 TCP 通訊協定。如要解決這個問題，您必須覆寫 Oracle JDBC 連線網址。

您可以提供 url 旗標，以解決這個問題，格式如下： jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE。 不必提供 oracle-service、host 和 port 旗標。Oracle 伺服器使用的 TCPS 通訊埠編號通常是 2484。

以下範例說明如何在指令中指定連線網址：

dwh-migration-dumper \
  --connector oracle-stats \
  --url "jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE" \
  --assessment \
  --driver "JDBC_DRIVER_PATH" \
  --user "USER" \
  --password

除了將連線通訊協定變更為 TCPS 之外，您可能還需要提供驗證 Oracle 伺服器憑證所需的 trustStore SSL 設定。如果缺少 SSL 設定，系統會顯示 Unable to find valid certification path 錯誤訊息。如要解決這個問題，請設定 JAVA_OPTS 環境變數：

set JAVA_OPTS=-Djavax.net.ssl.trustStore="JKS_FILE_LOCATION" -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword="PASSWORD"

視 Oracle 伺服器設定而定，您可能也需要提供 keyStore 設定。如要進一步瞭解設定選項，請參閱「SSL With Oracle JDBC Driver」(搭配 Oracle JDBC 驅動程式使用 SSL)。

後續步驟

• 進一步瞭解遷移作業總覽。
• 瞭解如何執行遷移評估。
• 瞭解如何使用互動式 SQL 翻譯器翻譯查詢。
• 瞭解如何使用批次 SQL 翻譯器遷移程式碼。
• 瞭解如何產生翻譯和評估的中繼資料。