将 Git 与 Lakeflow 作业配合使用

任务可以直接从远程 Git 存储库中签出源代码。

以下任务类型支持远程 Git 存储库：

• Notebooks
• Python脚本
• SQL 文件
• 数据生成工具 （dbt） 项目

作业中的所有任务都必须引用远程存储库中的同一提交记录。 作业运行开始时，Azure Databricks 会对指定的分支或提交进行快照，以便该运行中的所有任务都能够使用相同的代码版本。

查看运行存储在远程 Git 存储库中的代码的任务的运行历史记录时， “任务运行详细信息 ”窗格包括 Git 详细信息，包括与运行关联的提交 SHA。 请参阅查看任务运行历史记录。

使用 Git 存储库源与使用 Git 文件夹。

本页讨论可以直接从远程 Git 存储库拉取源代码的任务。 工作区还支持名为 Git 文件夹的功能，其中工作区中的文件夹与 Git 存储库同步。 任务可以使用 Git 文件夹作为其源。 但是，必须管理与存储库的同步。 如本处所述，使用远程 Git 存储库会在作业运行时自动拉取新的源码（如果可用）。

Azure Databricks建议仅引用 Git 文件夹中的工作区路径，以便在开发期间进行快速迭代和测试。 对于过渡和生产作业，请配置任务以改为引用远程 Git 存储库。

为任务配置 Git 提供商

作业 UI 有一个用于配置远程 Git 存储库的对话框。 可从 Git 标题下的“作业详细信息”窗格或配置为使用 Git 提供程序的任何任务中访问此对话框。 若要访问对话框，请单击“作业详细信息”窗格中的“添加 Git 设置”。

在 “Git ”对话框中（如果在任务配置期间访问了 Git 信息 ），请输入以下详细信息：

• Git 存储库 URL。
• 从下拉列表中选择 Git 提供程序 。
• 在“Git 引用”字段中，输入与要运行的源代码版本对应的分支、标记或提交标识符。
• 从下拉列表中选择 分支、 标记或 提交 。

必须仅指定以下项之一：

• “分支”：分支的名称，例如 main。
• 标记：标记的名称，例如 release-1.0.0。
• “提交”：特定提交的哈希值，例如 e0056d01。

对于运行存储在远程 Git 存储库中的代码的任务，查看其运行历史记录时，“任务运行详细信息”面板将包含 Git 详细信息，包括与运行关联的提交 SHA。 请参阅查看任务运行历史记录。

大型存储库的稀疏签出

对于大型存储库，可以使用稀疏签出仅导入特定目录，而不是整个存储库。 稀疏签出可降低作业运行时的签出时间和资源消耗。

但是，不正确的配置可能会导致缓存碎片，这会在整个工作区中降低执行时间。 本部分介绍使用稀疏结帐时可能出现的权衡和问题。

如何 Azure Databricks 缓存存储库检出

Azure Databricks 根据四个值对每个 Git 签出进行缓存：

• Workspace
• 存储库 URL
• 精确提交哈希
• 稀疏签出模式的指纹（确切的文件夹路径集）

与所有四个条件匹配的任何作业都会重复使用缓存条目，该条目最长有效期为一周。 例如，如果你有 3 个不同的作业，并且它们都具有相同的条件，则它们会使用相同的缓存到存储库，直到有新的提交（1 周后）。

每个唯一稀疏签出模式都会创建单独的指纹，因此会创建单独的缓存条目。 如果每个 20 个用户将自定义文件夹添加到其模式，则系统会创建 20 个不同的缓存键并导入共享文件夹树 20 次 ， 从而在工作区上增加负载。 创建一个包含其所有 20 个文件夹的稀疏签出模式（例如，将其作为一个父文件夹），这将允许单个缓存更频繁地工作，并在作业中提高性能。 权衡是签出中的更多文件。

决定是否使用稀疏签出

仅当您的使用场景符合以下两个条件时，才启用稀疏签出 (sparse checkout)：

• 大小：存储库很大（例如，它超过 2,500 个文件）。
• 稳定目标：目标分支不常更新（例如，大约每小时一次提交或更少）。 避免由于自动化 CI/CD 工作流而快速更改的分支。

如果使用稀疏签出，则组织还应采用以下一种或两种模式策略：

• 标准化：在整个组织中使用三种或更少的共享签出模式来最大程度地提高缓存命中率。
• 微目标定位：调整结构模式，以使每个模式专注于少量文件。 为了获得最佳性能，目标少于 200 个文件。

这有助于降低进口率。

计算导入率

在启用稀疏签出之前，请估计您的预计每小时文件导入速率。 所有作业和用户的限制都在工作区级别上应用。

每小时文件数 = 每小时作业运行次数 × 缓存未命中率 × 每次未命中导入的文件数

示例：180 次运行/小时× 10% 错率× 6,000 个文件/小时 = 108,000 个文件/小时

将结果与以下阈值进行比较：

最佳做法

标准化模式

• 操作：每个存储库发布三个或更少的已批准的稀疏模式。 共享模式合并负载并最大化缓存命中数。
• 不要：禁止每个团队自定义模式。 即使是一个额外的文件夹也会创建新的缓存条目，并触发完全的重新导入。

管理提交频次变化

• 执行：将作业指向稳定发布分支。 批量合并到预定的发布窗口中，以便多个执行可以共享相同的缓存提交记录。
• 请勿：将稀疏结帐与经常更新的分支一起使用，例如 master 或 main。 由于缓存是基于确切的提交哈希，因此每次新提交都会使缓存失效，并导致每个作业运行时需要完全重新导入。

管理负载

• Do：从源代码管理中删除大型二进制文件、生成的项目和数据文件，以无条件地减小存储库大小。
• 请勿使冗余作业以高频率运行。 对于不需要连续执行的作业，降低其触发频率；对于计划错开的作业，调整其时间表；或者，对于共享相同代码签出的作业，合并这些作业。

使用发布分支管理提交频繁变动

当作业以快速移动的分支为目标mastermain时，提交哈希会频繁更改，导致几乎每次运行时缓存未命中。 使用按固定计划进行更新的专用发布分支可提高缓存命中率。

通过将所有作业指向每小时发布分支，在同一小时内，所有运行都解析为同一提交哈希值，并共享同一缓存条目。

配置发布分支：

1. 在 Git 存储库中创建生存期较长的分支（例如 release-candidate）。
2. 自动更新此分支以按固定计划匹配 master ，例如每小时的顶端。
3. 请将使用 Git 的作业配置为使用 release-candidate 作为其目标 Git 参考。

在实现之前，请查看以下权衡：

示例：使用 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

Step 2：手动触发GitHub操作以验证是否已创建 release-candidate 分支。

步骤 3：更新现有作业以 release-candidate 用作目标 Git 引用。

使用作业 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 字符串都是相对于存储库根目录的目录路径。 每个指定目录中的所有文件都包含在签出中。