使用 Git 搭配 Lakeflow Jobs

工作任務可以直接從遠端 Git 倉庫借用原始碼。

以下任務類型支援遠端 Git 儲存庫：

  • Notebooks
  • Python 腳本
  • SQL 檔案
  • 資料建置工具（DBT）專案

某個作業中的所有任務都必須參考遠端存放庫中的相同提交。 當工作執行開始時，Azure Databricks 會對指定的分支或提交進行快照，確保該執行中的所有任務使用相同版本的程式碼。

當你查看執行儲存在遠端 Git 儲存庫的任務的執行歷史時，任務 執行細節 面板會包含 Git 細節，包括與執行相關聯的提交 SHA。 請參閱檢視任務執行歷程記錄。

備註

設定為使用遠端 Git 存放庫的工作無法寫入工作區檔案。 這些任務必須將暫存資料寫入附在驅動節點的臨時儲存，並將持久資料寫入磁碟區或資料表。

Git 儲存庫原始碼與 Git 資料夾的比較

本頁討論可直接從遠端 Git 倉庫擷取原始碼的任務。 工作區也支援一項叫做 Git 資料夾的功能，讓你的工作區中的資料夾與 Git 儲存庫同步。 任務可以使用 Git 資料夾作為來源。 不過，你必須管理與儲存庫的同步。 使用此處描述的遠端 Git 儲存庫，會在工作執行時自動拉取新原始碼（若有）。

Azure Databricks 建議僅在 Git 資料夾中參考工作區路徑，以便在開發過程中快速迭代和測試。 對於部署和生產作業，請設定任務以參考遠端 Git 儲存庫。

為某個工作配置 Git 提供者

作業 UI 有一個對話方塊可設定遠端 Git 存放庫。 此對話框可從 工作細節 窗格中的 Git 標題下進入，或在任何設定使用 Git 提供者的任務中。 要進入對話框，請在工作詳情欄格中點選「新增 Git 設定」。

在 Git 對話方塊中 （如果在工作設定期間存取，則標示為 Git 資訊 ），輸入下列詳細資料：

  • Git 存放庫 URL。
  • 從下拉選單中選擇您的 Git 供應商 。
  • 在 [Git 參考] 欄位中，輸入分支、標籤或提交的識別碼，以對應您想要執行的原始碼版本。
  • 從下拉選單選擇 分支、 標籤或 提交 。

您必須僅指定以下其中一項：

  • [分支]：分支的名稱，例如 main。
  • tag：標記的名稱，例如 release-1.0.0。
  • 提交：特定提交的雜湊，例如 e0056d01。

備註

對話框可能會提示您以下訊息：此帳戶缺少 Git 認證。請新增認證。 您必須先設定遠端 Git 存放庫，才能使用它作為參考。 請參見「配置 Git 資料夾整合」。

當你查看執行儲存在遠端 Git 儲存庫的任務的執行歷史時，任務 執行細節 面板會包含 Git 細節，包括與執行相關聯的提交 SHA。 請參閱檢視任務執行歷程記錄。

以角色身分執行 Git 作業

如果你的工作區使用 RBAC，你可以將作業的 Run as 身分設定為群組（角色）。 接著該工作會用 角色的 Git 憑證複製它的 Git 儲存庫，因此管理者必須先設定該憑證，否則工作將無法複製。 若要將工作的 Run as 設為群組，請參閱 將 Run as 設為群組。

若要修正因程式碼問題而失敗的作業，請在該作業的存放庫和分支上使用其中一種 撰寫方式。 假設角色要重現並修正該問題，提交修正，然後重新執行該工作。

大型倉庫的稀疏檢出

對於大型存放庫，你可以用稀疏檢查（sparse checkout）只匯入特定目錄，而无需匯入完整儲存庫。 稀疏檢出可以減少每次工作執行時的檢出時間和資源使用。

然而，設定不當會導致快取碎片化，進而降低整個工作區的執行時間。 本節說明使用稀疏結帳時可能需考量的權衡與可能出現的問題。

Azure Databricks 如何快取儲存庫簽出

Azure Databricks 會根據四個值緩存每個 Git checkout：

  • Workspace
  • 存放庫 URL
  • 確切的提交哈希值
  • 稀疏結帳模式的指紋（資料夾路徑的精確集合）

任何符合四項條件的工作執行都會重複使用快取條目，該快取條目可持續有效至多達一週。 舉例來說，如果你有 3 個不同的作業，且它們的條件皆相同，則它們會對該儲存庫共用同一份快取，直到有新的提交版本為止（或在 1 週後）。

每個獨特的稀疏檢出模式都會產生獨立的指紋，因此也會產生獨立的快取項目。 如果有 20 位使用者各自新增一個自訂資料夾到他們的模式中，系統會建立 20 個不同的快取鍵，並將共享資料夾樹匯入 20 次，增加工作空間的負擔。 建立一個包含所有 20 個資料夾的稀疏結出模式（例如，它是一個父資料夾），可以讓單一快取更頻繁地運作，並在你的工作中獲得更好的效能。 代價是結帳時會有更多檔案。

決定是否使用稀疏結帳

只有當你的使用情境符合以下兩個條件時，才啟用稀疏結帳：

  • 大小：你的資料庫很大（例如超過2,500個檔案）。
  • 穩定目標設定：目標分支更新頻率不高（例如每小時約一次提交）。 避免因自動化 CI/CD 工作流程而快速變動的分支。

若使用稀疏結帳，您的組織也應採用以下一項或兩種模式策略之一：

  • 標準化：在組織內使用三個或更少的共用結帳模式，以最大化快取點擊率。
  • 微目標化：調整模式，使每個模式專注於少量檔案。 為了達到最佳效能，目標檔案少於 200 個。

這些能幫助降低進口率。

計算你的進口率

啟用稀疏結帳前，先估算你預計的 每小時檔案 匯入率。 限制適用於工作區層級，涵蓋所有工作與使用者。

每小時檔案數 = 每小時執行的工作次數 ×快取未命中率×每次未中匯入檔案數

因素 驅動它的動力
每小時作業執行次數 所有使用者的觸發頻率
快取遺漏率 目標分支的提交頻率及獨特稀疏模式集的數量
每次失誤匯入的檔案数量 總儲存庫大小或稀疏檢出子集大小

範例：每小時 180 次運行 × 10% 未命中率 × 每次未命中 6,000 檔案 = 每小時 108,000 檔案

請將你的結果與以下門檻做比較：

每小時匯入檔案數 預期工作空間影響
低於15萬人 正常運作
150,000 – 300,000 性能下降。 有些工作可能會遇到延誤或失敗。
超過30萬人 工作無法可靠地完成。

最佳實務

標準化模式

  • 建議：每個儲存庫發布三個或更少的核准稀疏模式。 共享模式整合負載並最大化快取命中率。
  • 不要：允許自訂每隊的圖案。 即使新增一個資料夾，也會產生新的快取項目，並觸發全面重新匯入。

管理提交頻繁變更

  • 該做：將工作指向穩定的釋出分支。 批次合併到排程的發佈視窗，讓多個執行共享同一個快取的提交。
  • 不要：使用頻繁更新分支的稀疏結帳，如 master 或 main。 由於快取是基於精確的提交雜湊值，每次新的提交都會使快取失效，並導致每次工作執行都必須完全重新匯入。

管理負載

  • 建議：從原始碼控制中移除大型二進位檔、產生的產物和資料檔案，無條件降低儲存庫大小。
  • 不要：讓多餘的工作以高頻率運行。 對於不需要連續執行、不需錯開排程或合併共用同一結帳的作業，觸發頻率較低。

用發佈分支管理提交變動頻率

當工作針對更動頻繁的分支如 master 或 main時，提交哈希常常變動，導致幾乎每次執行都發生快取失誤。 使用按固定時間表更新的專屬發佈分支能提升快取命中率。

透過將所有工作指向每小時的釋放分支，該一小時內的所有執行都會解析到相同的提交雜湊並共享相同的快取項目。

要設定釋出分支：

  1. 在你的 Git 倉庫中建立一個長壽命的分支（例如 release-candidate）。
  2. 自動更新此分支，使其符合 master 固定時間表，例如每小時的開始。
  3. 將您基於 Git 的工作設置為以 release-candidate 作為其目標 Git 參考。

在實施前，請先檢視這些取捨：

考量事項 說明
提交延遲 工作會依據代碼執行，落後最多一小時 master。 這對大多數批次工作負載來說是可接受的，但可能不適合需要最新提交的工作。
故障視窗 若發佈裁切工作失敗，該小時內分支版本不會更新，工作會繼續對先前的提交執行。 Databricks 建議對中斷的作業發出警示。

範例：使用 GitHub Actions 自動化

以下的 GitHub Actions 工作流程每小時自動執行一次發佈分支的分割。

步驟 1：將檔案提交 .github/workflows/cut-release-branch.yml 到你的儲存庫：

name: Cut Hourly Release Candidate

on:
  schedule:
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-branch:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout main branch
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: Update release-candidate branch
        run: |
          git push origin HEAD:release-candidate --force

步驟 2：手動觸發 GitHub 動作以確認 release-candidate 分支已建立。

步驟三：將你現有的工作更新為使用 release-candidate 作為目標 Git 參考。

使用 Jobs API 啟用稀疏檢出。

為了啟用稀疏簽出，請在建立或更新工作時於sparse_checkout內加入git_source區塊：

{
  "git_source": {
    "git_url": "https://github.com/example/my-repo",
    "git_provider": "gitHub",
    "git_branch": "release-candidate",
    "sparse_checkout": {
      "patterns": ["src/models", "src/utils"]
    }
  }
}

每個字 patterns 串都是相對於儲存庫根的目錄路徑。 每個指定目錄中的所有檔案都會包含在取出操作中。

  • Last updated on