排解遷移問題

本文說明如何排解將資料倉儲 (例如 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 錯誤

這個錯誤可能是因為記錄掛鉤 JAR 檔案放置位置錯誤所致。請確認您已將 JAR 檔案新增至 Hive 叢集上的 auxlib 資料夾。或者，您可以在 hive.aux.jars.path 屬性中指定 JAR 檔案的完整路徑，例如 file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar。

設定的資料夾中不會顯示子資料夾

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

在 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 錯誤。

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

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

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

批次 SQL 翻譯器

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

RelationNotFound 或 AttributeNotFound 翻譯問題

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

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

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

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

使用 Gemini 修正翻譯問題

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

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

  3. 如要前往程式碼分頁中含有錯誤的檔案和行，請按一下

    錯誤訊息。

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

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

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

生成翻譯和評估的中繼資料

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

「記憶體不足」錯誤

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

您可以匯出 JAVA_OPTS 環境變數，藉此增加記憶體上限：

Linux

export JAVA_OPTS="-Xmx4G"

Windows

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 檔案 並執行下列指令：

Bash 

sha256sum --check SHA256SUMS.txt

OK 結果表示總和檢查碼驗證成功。其他任何訊息都表示驗證錯誤：

  • FAILED: computed checksum did NOT match：ZIP 檔案已毀損，必須重新下載。
  • FAILED: listed file could not be read：系統找不到 ZIP 檔案版本。從相同發布版本下載總和檢查碼和 ZIP 檔案，並放在相同目錄中。

Windows PowerShell 

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

將 RELEASE_ZIP_FILENAME 替換成 dwh-migration-dumper 指令列擷取工具版本的下載 ZIP 檔案名稱，例如 dwh-migration-tools-v1.0.52.zip。

True 結果會確認總和檢查碼驗證是否成功。

False 結果表示驗證錯誤。從相同發布版本下載總和檢查碼和 ZIP 檔案，並放在相同目錄中。

Teradata 查詢記錄擷取作業緩慢

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

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

Bash

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

Windows PowerShell

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 個半形字元：

Bash

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

Windows PowerShell

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

下列指令顯示如何使用 -Dteradata-logs.max-sql-length 標記，將長查詢文字分割成多列，每列最多 10,000 個半形字元：

Bash

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

Windows PowerShell

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」。

後續步驟