新 LookML：如何轉換 YAML LookML 專案

Looker 4.0 推出了新的 LookML 語法，改進了原始的 YAML 風格 LookML，提供更簡單的語法和豐富且輔助性強的 IDE，讓 LookML 開發作業更輕鬆。從 Looker 4.4 起，所有新的 LookML 專案都必須使用新 LookML 建立；不過，轉換前建立的部分專案可能仍以 YAML (舊版) LookML 建立模型。

Looker 提供自動化方式，可將 YAML LookML 專案轉換為新 LookML。本頁說明如何執行這項程序。每個 LookML 專案都需要個別轉換，開發人員必須準備和協調相關工作，因此請務必先將本頁內容讀完，再轉換專案。

準備轉換

將 YAML LookML 專案轉換為新 LookML 的任務必須由一位 LookML 開發人員執行。轉換會在開發人員的開發模式中進行，然後變更會像任何一般 LookML 變更一樣提交及部署。

不過，這個程序需要所有 LookML 開發人員的合作。由於轉換作業會修改所有 LookML 程式碼行，因此請務必確保其他 LookML 開發人員已在轉換程序開始前，將所有變更提交並部署至專案。否則可能會導致一些非常嚴重的 Git 合併衝突。

雖然轉換程序是自動化，但新的 LookML 比 YAML LookML 更徹底地進行錯誤檢查。也就是說，轉換後可能會顯示先前未顯示的錯誤。解決這些錯誤可改善專案品質。每個專案的錯誤數量都會有所不同，因此修正這些錯誤可能需要幾分鐘到幾小時不等。無論如何，所有 LookML 開發人員都必須暫停專案開發作業，直到錯誤修正為止。

在 Looker 執行個體中尋找 YAML 專案

如要在 Looker 執行個體上查看 YAML 專案，請按照下列步驟操作：

  1. 在「Develop」選單中，選取「Manage LookML Projects」或「Projects」選項 (選項會因您存取「Develop」選單的位置而略有不同)。
  2. 在「LookML 專案」頁面中，找出專案表格資料列中的「YAML LookML」標籤：

    提示：您可以在表格中選取專案名稱，前往專案的 LookML。

轉換前請與開發人員協調

如要準備轉換至新 LookML，請按照下列步驟操作：

  1. 請選擇一位 LookML 開發人員來執行轉換程序。
  2. 請執行 LookML 驗證工具，確認專案沒有錯誤。請修正所有錯誤，然後提交及部署變更，再繼續進行下一個步驟。
  3. 指定要執行轉換的時間。
  4. 請通知所有其他 LookML 開發人員，他們必須在指定時間前提交及部署所做的任何變更。也就是說，專案的所有開發模式副本都應處於「與正式版同步」的 Git 狀態。
  5. 請通知其他 LookML 開發人員，在轉換完成前，他們「不應」進行、提交或部署任何變更。

轉換為新的 LookML

如要轉換為新的 LookML，請執行轉換器：

  1. 進入開發模式。
  2. 開啟要轉換的專案。
  3. 確認左上角的 Git 狀態顯示「Up to Date」，並與「Production」保持一致。
  4. 執行 LookML 驗證工具，確保專案中沒有錯誤。結果應為「No LookML Issues」。(如要執行 LookML 驗證工具，請選取 Looker IDE 右上方的「Validate LookML」按鈕；或者選取 IDE 頂端的「Project Health」圖示，開啟「Project Health」面板，然後選取「Validate LookML」。)
  5. 如要將專案從 YAML LookML 轉換為新 LookML：

    1. 在 Looker IDE 的導覽側欄中選取「Git Actions」圖示。
      • 或者，您也可以選取 IDE 頂端的「Project Health」圖示：

    2. 從「Git 動作」面板或「專案健康狀況」面板底部選取「將專案轉換為新 LookML」選項。
    3. 在確認對話方塊中選取「轉換為新 LookML」按鈕。

驗證新的 LookML

轉換器執行完畢後，IDE 會在每個檔案名稱旁邊加上一個點，表示檔案已變更：

如要驗證新的 LookML，請按照下列步驟操作：

  1. 選取「驗證 LookML」按鈕，執行 LookML 驗證工具。 如果沒有錯誤，您可以略過本頁的提交並部署新 LookML 部分。
  2. 您可能會在先前沒有錯誤的地方看到錯誤。如先前所述，新版 LookML 比 YAML LookML 更徹底地檢查錯誤。請查看並修正錯誤。如果無法順利解決問題，請參閱本頁結尾的「解決錯誤」一節。

提交及部署新的 LookML

此時，請按照任何一般 LookML 變更的方式，提交及部署。請注意：這項提交作業會觸發永久衍生資料表 (PDT) 的重建作業。提交完成後，請讓其他 LookML 開發人員知道轉換已完成，且依賴 PDT 的查詢可能需要比平常更長的時間才能執行，至少要等到所有內容都重建完成。開發人員現在可以透過開發模式從實際環境中提取資料，導入變更，然後繼續開發，而且還可使用更直覺的 LookML 語法和更實用強大的 IDE。

解決錯誤

由於新版 LookML 的模型驗證更為徹底，您在轉換後可能會看到先前未顯示的錯誤。此外，在某些情況下，新版 LookML 的 ad hoc 錯誤檢查需要更多資訊；轉換工具會嘗試為您找出這些資訊，但在某些情況下，您可能需要在一個或兩個檢視畫面檔案中新增額外的 include 行。

無效的欄位參照

在某些情況下，YAML (舊版) LookML 無法確保您參照的欄位或集合確實已在模型中定義。最有可能顯示此值的地方是鑽研欄位清單和集合。

舉例來說，如果舊版 LookML 包含 drill_fields: [id, name, email]，但在模型開發過程中，您移除了 name 欄位，改用 first_name 和 last_name 欄位，YAML LookML 不會警告您在鑽研欄位清單中參照的欄位 (name) 不存在。如果您在維度群組中參照欄位，而您的 YAML LookML 未以新 LookML 的方式指定欄位，也會發生這個問題。

不過，新版 LookML 會顯示這類錯誤。因此，在轉換專案並執行 LookML 驗證工具後，您可能會看到有關無效欄位參照的錯誤，而這類錯誤先前並未出現。修正這些錯誤可改善模型的整體品質。

檢視檔案中缺少包含項目

在某些情況下，新版 LookML 的臨時錯誤檢查需要比 YAML LookML 更豐富的背景資訊。具體來說，您可能需要在部分檢視畫面檔案中放置 include 行，最常見的情況是當一個檢視畫面延伸至另一個檢視畫面時。

如果檢視中所需的檔案沒有任何歧義，轉換器會自動在新的 LookML 檢視檔案中加入適當的 include 宣告，您就不會看到任何錯誤。

不過，在某些情況下 (例如專案包含多個模型)，可能會有兩個以上的檢視畫面在不同的檢視畫面檔案中宣告相同名稱。轉換工具無法判斷哪一個是正確的要納入的檢視畫面，因此會在新的 LookML 檔案頂端新增註解，指出只應納入其中一個檢視畫面。如要解決產生的錯誤，請前往檢視檔案並取消註解正確的建議。

Stranded extension_required Explores

如同先前所述的無效欄位參照問題，在新的 LookML 中，LookML 驗證工具會針對使用 extension: required 宣告但實際上未擴充的探索，發出警告。如要解決這項錯誤，請將這些探索重新連結至其擴充物件，如果未使用，請將其移除。

版本管控

由於 LookML 轉換程序會將 .lookml 檢視畫面和模型檔案替換為 .lkml 版本，因此如果有一位或多位開發人員在轉換期間對專案進行提交，您就會遇到合併衝突。因此，請務必只讓一位開發人員執行轉換工具，並在開始轉換程序前，協調確保每位開發人員的開發模式副本都已清除並更新。

為避免版本控制問題，轉換期間必須凍結程式碼。其他開發人員不應在轉換功能遭封鎖期間提交變更。

如果執行轉換的開發人員在轉換過程中遇到問題，但尚未提交變更並推送至正式環境，則建議他們將應用程式還原至正式環境。下拉式選單中的這個選項 (請參閱本頁「執行轉換器」部分的圖片) 會撤銷轉換作業，讓開發人員重新開始轉換程序。