`bundle` 命令组

2025-09-15

注意

此信息适用于 Databricks CLI 版本 0.205 及更高版本。 Databricks CLI 目前处于公共预览版阶段。

Databricks CLI 的使用须遵守 Databricks 许可和 Databricks 隐私声明，包括任何数据使用规定。

bundle Databricks CLI 中的命令组包含用于管理 Databricks 资产捆绑包的命令。借助 Databricks 资产捆绑包，可以将项目表示为代码，以编程方式验证、部署和运行 Azure Databricks 工作流，例如 Azure Databricks 作业、 Lakeflow 声明性管道和 MLOps Stacks。请参阅什么是 Databricks 资产捆绑包？。

注意

捆绑包命令在捆绑文件夹内运行时使用其中的设置databricks.yml进行身份验证。如果您想在捆绑文件夹中运行具有不同身份验证的捆绑命令，请使用（或--profile）标志指定-p，并且不要指定--target。

或者，从捆绑文件夹外部运行不需要与捆绑包相同的身份验证的命令。

databricks 捆绑包部署

将捆绑包部署到远程工作区。

databricks bundle deploy [flags]

捆绑目标和标识

若要将捆绑包部署到特定目标，请将 -t（或 --target）选项与捆绑包配置文件中声明的目标名称一起设置。如果未指定命令选项，会使用捆绑包配置文件中声明的默认目标。例如，对于使用名称dev声明的目标：

databricks bundle deploy -t dev

可将捆绑包部署到多个工作区，例如开发、暂存和生产工作区。从根本上说，root_path 属性决定了捆绑包的唯一标识，它默认为 ~/.bundle/${bundle.name}/${bundle.target}。因此，默认情况下，捆绑包的标识由部署者的标识、捆绑包的名称和捆绑包的目标名称组成。如果这些属性在不同的捆绑包中相同，则这些捆绑包的部署会互相干扰。

此外，捆绑包部署将跟踪通过其 ID 在目标工作区中创建的资源，作为存储在工作区文件系统中的状态。资源名称不用于在捆绑包部署和资源实例之间关联，因此：

如果捆绑包配置中的资源不存在于目标工作区中，则会创建该资源。
如果捆绑包配置中的资源存在于目标工作区中，则会在工作区中更新该资源。
如果资源已从捆绑包配置中删除，则会从目标工作区中删除该资源（如果之前已部署）。
仅当你更改捆绑包名称、捆绑包目标或工作区时，才能忘记资源与捆绑包的关联。可以运行 bundle validate 来输出包含这些值的摘要。

选项

--auto-approve

跳过可能需要部署的交互式审批。

-c, --cluster-id string

使用给定群集 ID 替代部署中的群集。

--fail-on-active-runs

如果部署中有正在运行的作业或管道，则失败。

--force

强制重写 Git 分支验证。

--force-lock

强制获取部署锁。

全局标志

例子

以下示例使用特定群集 ID 部署捆绑包：

databricks bundle deploy --cluster-id 0123-456789-abcdef

databricks 捆绑包部署

与部署相关的命令。

databricks bundle deployment [command]

可用命令

bind - 将捆绑定义的资源绑定到远程工作区中的现有资源。
unbind - 从其远程资源取消绑定捆绑定义的资源。

databricks 捆绑包部署绑定

将捆绑包定义的资源链接到 Azure Databricks 工作区中的现有资源，以便它们由 Databricks 资产捆绑包管理。如果绑定某个资源，则现有工作区中的 Azure Databricks 资源会在下一个 bundle deploy之后，根据捆绑包中定义的配置进行更新。

databricks bundle deployment bind KEY RESOURCE_ID [flags]

绑定不会重新创建数据。例如，如果目录中具有数据的管道已应用绑定，则可以部署到该管道，而不会丢失现有数据。此外，例如，无需重新计算物化视图，管道因此不必重新运行。

绑定命令应与--target标记一起使用。例如，使用 databricks bundle deployment bind --target prod my_pipeline 7668611149d5709ac9-2906-1229-9956-586a9zed8929 将生产部署绑定到生产管道

提示

在运行绑定之前，最好先确认工作区中的资源。

以下资源支持绑定：

Arguments

KEY

要绑定的资源密钥

RESOURCE_ID

要绑定到的现有资源的 ID

选项

--auto-approve

自动批准绑定，而不是提示

--force-lock

强制获取部署锁。

全局标志

例子

以下命令将资源 hello_job 绑定到工作区中的远程对应资源。该命令会输出差异，并允许拒绝资源绑定，但如果确认，捆绑包中对作业定义的任何更新会在下次部署捆绑包时应用于相应的远程作业。

databricks bundle deployment bind hello_job 6565621249

databricks 捆绑部署取消绑定

删除捆绑包中的资源与其工作区中的远程对应项之间的链接。

databricks bundle deployment unbind KEY [flags]

Arguments

KEY

要取消绑定的资源键

选项

--force-lock

强制获取部署锁。

全局标志

例子

以下示例取消绑定 hello_job 资源：

databricks bundle deployment unbind hello_job

databricks 捆绑包销毁

警告

销毁捆绑包会永久删除捆绑包以前部署的作业、管道和项目。此操作不可撤消。

删除以前部署的作业、管道、其他资源和项目。

databricks bundle destroy [flags]

注意

捆绑包的标识由捆绑包名称、捆绑包目标和工作区组成。如果更改了其中任何一项，然后尝试在部署之前销毁捆绑包，将发生错误。

默认情况下，系统会提示你是否确认要永久删除以前部署的作业、管道和项目。若要跳过这些提示并执行自动永久删除，请将 --auto-approve 选项添加到 bundle destroy 命令。

选项

--auto-approve

跳过用于删除资源和文件的交互式审批

--force-lock

强制获取部署锁。

全局标志

例子

以下命令删除捆绑配置文件中定义的所有以前部署的资源和项目：

databricks bundle destroy

databricks 捆绑包生成

为 Databricks 工作区中已存在的资源生成捆绑配置。支持以下资源：应用、仪表板、作业、管道。

默认情况下，此命令在捆绑项目的*.yml文件夹中为资源生成resources文件，并下载配置中引用的任何文件，例如笔记本。

重要

bundle generate 命令为方便自动生成资源配置提供。但是，当资源配置包含在捆绑包中并部署时，它将创建一个新资源，除非已首次使用，否则不会更新现有资源 bundle deployment bind 。请参阅 databricks 包部署绑定。

databricks bundle generate [command]

可用命令

app - 为 Databricks 应用生成捆绑配置。
dashboard - 为仪表板生成配置。
job - 为作业生成捆绑配置。
pipeline - 为管道生成捆绑配置。

选项

--key string

用于生成的配置的资源密钥

全局标志

databricks 捆绑包生成仪表板

为工作区中的现有仪表板生成配置。

databricks bundle generate dashboard [flags]

提示

要在部署仪表板后更新 .lvdash.json 文件，请在运行 --resource 时使用 bundle generate dashboard 选项，以生成现有仪表板资源的文件。要持续轮询和检索仪表板的更新，请使用 --force 和 --watch 选项。

选项

-s, --dashboard-dir string

将仪表板表示形式写入到的目录（默认为“src”）

--existing-id string

要为其生成配置的仪表板的 ID

--existing-path string

要为其生成配置的仪表板的工作区路径

-f, --force

强制覆盖输出目录中的现有文件

--resource string

要监视更改的仪表板的资源密钥

-d, --resource-dir string

要将配置写入到的目录（默认的“resources”）

--watch

监视仪表板的更改并更新配置

全局标志

例子

以下示例通过现有仪表板 ID 生成配置：

databricks bundle generate dashboard --existing-id abc123

还可以按工作区路径为现有仪表板生成配置。从工作区 UI 复制仪表板的工作区路径。

例如，以下命令在包含下列 YAML 的 baby_gender_by_county.dashboard.yml 捆绑包项目文件夹中生成一个新的 resources 文件，并将 baby_gender_by_county.lvdash.json 文件下载到 src 项目文件夹。

databricks bundle generate dashboard --existing-path "/Workspace/Users/someone@example.com/baby_gender_by_county.lvdash.json"

# This is the contents of the resulting baby_gender_by_county.dashboard.yml file.
resources:
  dashboards:
    baby_gender_by_county:
      display_name: 'Baby gender by county'
      warehouse_id: aae11o8e6fe9zz79
      file_path: ../src/baby_gender_by_county.lvdash.json

databricks 捆绑包生成作业

为作业生成捆绑配置。

注意

目前，此命令仅支持包含笔记本任务的作业。

databricks bundle generate job [flags]

选项

-d, --config-dir string

输出配置将存储的 Dir 路径（默认的“resources”）

--existing-job-id int

要为其生成配置的作业的作业 ID

-f, --force

强制覆盖输出目录中的现有文件

-s, --source-dir string

将存储已下载文件的 Dir 路径（默认为“src”）

全局标志

例子

以下示例在hello_job.yml捆绑项目文件夹中生成一个新resources文件，其中包含下面的 YAML，并将该文件simple_notebook.py下载到src项目文件夹。

databricks bundle generate job --existing-job-id 6565621249

# This is the contents of the resulting hello_job.yml file.
resources:
  jobs:
    hello_job:
      name: 'Hello Job'
      tasks:
        - task_key: run_notebook
          email_notifications: {}
          notebook_task:
            notebook_path: ../src/simple_notebook.py
            source: WORKSPACE
          run_if: ALL_SUCCESS
      max_concurrent_runs: 1

databricks 捆绑包生成管道

为管道生成捆绑配置。

databricks bundle generate pipeline [flags]

选项

-d, --config-dir string

输出配置将存储的 Dir 路径（默认的“resources”）

--existing-pipeline-id string

要为其生成配置的管道的 ID

-f, --force

强制覆盖输出目录中的现有文件

-s, --source-dir string

将存储已下载文件的 Dir 路径（默认为“src”）

全局标志

例子

以下示例为现有管道生成配置：

databricks bundle generate pipeline --existing-pipeline-id abc-123-def

databricks 捆绑初始化

使用捆绑模板初始化新捆绑包。可以将模板配置为提示用户输入值。请参阅 Databricks 资产捆绑项目模板。

databricks bundle init [TEMPLATE_PATH] [flags]

Arguments

TEMPLATE_PATH

用于初始化的模板（可选）

选项

--branch string

用于模板初始化的 Git 分支

--config-file string

包含模板初始化所需的输入参数的键值对的 JSON 文件。

--output-dir string

要向其写入初始化模板的目录。

--tag string

用于模板初始化的 Git 标记

--template-dir string

包含模板的 Git 存储库中的目录路径。

全局标志

例子

以下示例提示输入要从中选择的默认捆绑模板列表：

databricks bundle init

以下示例使用默认 Python 模板初始化捆绑包：

databricks bundle init default-python

若要使用自定义 Databricks 资产捆绑模板创建 Databricks 资产捆绑包，请指定自定义模板路径：

databricks bundle init <project-template-local-path-or-url> \
--project-dir="</local/path/to/project/template/output>"

以下示例从 Git 存储库初始化捆绑包：

databricks bundle init https://github.com/my/repository

以下示例使用特定分支进行初始化：

databricks bundle init --branch main

databricks 捆绑包已打开

导航到工作区中的捆绑资源，指定要打开的资源。若未指定资源键，此命令将输出要从中选择的捆绑包资源的列表。

databricks bundle open [flags]

选项

--force-pull

跳过本地缓存并从远程工作区加载状态

全局标志

例子

以下示例启动浏览器并导航到 baby_gender_by_county 为捆绑包配置的 Databricks 工作区中的捆绑包中的仪表板：

databricks bundle open baby_gender_by_county

databricks 捆绑包运行

运行作业、管道或脚本。如果未指定资源，则命令提示符会提示要从中选择的已定义的作业、管道和脚本。或者，指定捆绑配置文件中声明的作业或管道密钥或脚本名称。

databricks bundle run [flags] [KEY]

验证管道

如果要执行管道验证运行，请使用 --validate-only 选项，如以下示例所示：

databricks bundle run --validate-only my_pipeline

传递作业参数

要传递作业参数，请使用 --params 选项，后跟逗号分隔的键值对，其中键是参数名称。例如，以下命令将作业 message 的名为 HelloWorld 的参数设置为 hello_job：

databricks bundle run --params message=HelloWorld hello_job

注意

如以下示例所示，可以使用作业任务选项将参数传递给作业任务，但 --params 建议使用此选项传递作业参数。如果为未定义作业参数的作业指定了作业参数，或者为已定义作业参数的作业指定了任务参数，则会发生错误。

还可以指定关键字或位置参数。如果指定的作业使用作业参数或作业具有具有参数的笔记本任务，则标志名称将映射到参数名称：

databricks bundle run hello_job -- --key1 value1 --key2 value2

或者，如果指定的作业不使用作业参数，并且该作业具有 Python 文件任务或 Python 滚轮任务：

databricks bundle run my_job -- value1 value2 value3

执行脚本

若要使用捆绑包配置的身份验证凭据执行集成测试等脚本，可以内联运行脚本，也可以运行捆绑配置中定义的脚本。脚本使用捆绑包中配置的相同身份验证上下文运行。

在 -- 后附加双连字符 (bundle run) 以内联运行脚本。例如，以下命令输出当前用户的当前工作目录：
```
databricks bundle run -- python3 -c 'import os; print(os.getcwd())'
```
或者，在捆绑配置中的 scripts 映射中定义脚本，然后使用 bundle run 来运行脚本。
```
scripts:
  my_script:
    content: python3 -c 'import os; print(os.getcwd())'
```
```
databricks bundle run my_script
```
有关配置的详细信息 scripts ，请参阅脚本和脚本。

捆绑身份验证信息使用环境变量传递到子进程。请参阅 Databricks 统一身份验证。

Arguments

KEY

要运行的资源的唯一标识符（可选）

选项

--no-wait

不要等待运行完成。

--restart

如果正在运行，请重启运行。

全局标志

作业标志

以下标志是作业级参数标志。请参阅配置作业参数。

--params stringToString

作业参数的逗号分隔 k=v 对（默认值 []）

作业任务标志

以下标志是任务级参数标志。请参阅配置任务参数。 Databricks 建议对任务级参数使用作业级参数（--params）。

--dbt-commands strings

用于执行 DBT 任务的作业的命令列表。

--jar-params strings

包含 Spark JAR 任务的作业的参数列表。

--notebook-params stringToString

从键映射到具有笔记本任务的作业的值。（默认值 []）

--pipeline-params stringToString

从具有管道任务的作业的键到值的映射。（默认值 []）

--python-named-params stringToString

使用 Python 滚轮任务的作业的键到值映射。（默认值 []）

--python-params strings

包含 Python 任务的作业的参数列表。

--spark-submit-params strings

包含 Spark 提交任务的作业的参数列表。

--sql-params stringToString

从键映射到具有 SQL 任务的作业的值。（默认值 []）

管道标志

以下标志是管道标志。

--full-refresh strings

要重置和重新计算的表列表。

--full-refresh-all

执行完整的图形重置和重新计算。

--refresh strings

要更新的表的列表。

--refresh-all

执行完整的图形更新。

--validate-only

执行更新以验证图形正确性。

例子

以下示例在默认目标中运行作业 hello_job ：

databricks bundle run hello_job

以下示例在用名称hello_job声明的目标上下文中运行作业dev：

databricks bundle run -t dev hello_job

以下示例取消并重启现有作业运行：

databricks bundle run --restart hello_job

以下示例运行完全刷新的管道：

databricks bundle run my_pipeline --full-refresh-all

以下示例在捆绑上下文中执行命令：

databricks bundle run -- echo "hello, world"

databricks 捆绑架构

显示捆绑配置的 JSON 架构。

databricks bundle schema [flags]

选项

全局标志

例子

以下示例输出捆绑配置的 JSON 架构：

databricks bundle schema

若要将捆绑配置架构输出为 JSON 文件，请 bundle schema 运行该命令并将输出重定向到 JSON 文件。例如，可以生成在当前目录中命名 bundle_config_schema.json 的文件：

databricks bundle schema > bundle_config_schema.json

databricks 捆绑包摘要

输出捆绑包的标识和资源摘要，包括资源的深层链接，以便可以轻松导航到 Databricks 工作区中的资源。

databricks bundle summary [flags]

提示

还可使用 bundle open 导航到 Databricks 工作区中的资源。请参阅 databricks 捆绑包打开。

选项

--force-pull

跳过本地缓存并从远程工作区加载状态

全局标志

例子

以下示例输出捆绑包的已部署资源的摘要：

databricks bundle summary

以下输出是用于 my_pipeline_bundle 定义作业和管道的捆绑包的摘要：

Name: my_pipeline_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/my_pipeline/dev
Resources:
  Jobs:
    my_project_job:
      Name: [dev someone] my_project_job
      URL:  https://myworkspace.cloud.databricks.com/jobs/206000809187888?o=6051000018419999
  Pipelines:
    my_project_pipeline:
      Name: [dev someone] my_project_pipeline
      URL:  https://myworkspace.cloud.databricks.com/pipelines/7f559fd5-zztz-47fa-aa5c-c6bf034b4f58?o=6051000018419999

databricks 捆绑包同步

在本地文件系统目录中对捆绑包的文件更改执行单向同步，同步到远程 Azure Databricks 工作区中的目录。

注意

bundle sync 命令无法将远程 Azure Databricks 工作区内的目录中的文件更改同步回到本地文件系统中的目录。

databricks bundle sync [flags]

databricks bundle sync 命令的工作原理与 databricks sync 命令相同，且都用于提高工作效率。有关命令使用情况信息，请参阅 sync 命令。

选项

--dry-run

模拟同步执行而不进行实际更改

--full

执行完全同步（默认值为增量）

--interval duration

文件系统轮询间隔（for --watch）（默认 1s）

--output type

输出格式的类型

--watch

监视本地文件系统的更改

全局标志

例子

以下示例执行试运行同步：

databricks bundle sync --dry-run

以下示例自动监视更改和同步：

databricks bundle sync --watch

以下示例执行完全同步：

databricks bundle sync --full

databricks 捆绑包验证

验证捆绑配置文件语法正确。

databricks bundle validate [flags]

默认情况下，此命令会返回捆绑包标识的摘要：

Name: MyBundle
Target: dev
Workspace:
  Host: https://my-host.cloud.databricks.com
  User: someone@example.com
  Path: /Users/someone@example.com/.bundle/MyBundle/dev

Validation OK!

注意

如果资源属性是在捆绑配置文件中定义的，而在相应对象的架构中找不到这些文件，则 bundle validate 命令会输出警告。

若只想输出捆绑包标识和资源的摘要，请使用捆绑包摘要。

选项

全局标志

例子

以下示例验证捆绑包配置：

databricks bundle validate

全局标志

--debug

是否启用调试日志记录。

-h 或 --help

显示 Databricks CLI、相关命令组或相关命令的帮助。

--log-file 字符串

一个字符串，表示要将输出日志写入到的文件。如果未指定此标志，则默认会将输出日志写入到 stderr。

--log-format 格式

日志格式类型，text 或 json。默认值为 text。

--log-level 字符串

一个表示日志格式级别的字符串。如果未指定，则禁用日志格式级别。

-o, --output 类型

命令输出类型为 text 或 json。默认值为 text。

-p, --profile 字符串

要用于运行命令的 ~/.databrickscfg 文件中的配置文件名称。如果未指定此标志，并且存在命名为 DEFAULT 的配置文件，则使用该配置文件。

--progress-format 格式

显示进度日志的格式： default、 append、 inplace或 json

-t, --target 字符串

如果适用，要使用的捆绑包目标

--var strings

为捆绑配置中定义的变量设置值。例： --var="foo=bar"

共用方式為

bundle 命令组

databricks 捆绑包部署

捆绑目标和标识

选项

例子

databricks 捆绑包部署

可用命令

databricks 捆绑包部署绑定

Arguments

选项

例子

databricks 捆绑部署取消绑定

Arguments

选项

例子

databricks 捆绑包销毁

选项

例子

databricks 捆绑包生成

可用命令

选项

databricks 捆绑包生成仪表板

选项

例子

databricks 捆绑包生成作业

选项

例子

databricks 捆绑包生成管道

选项

例子

databricks 捆绑初始化

Arguments

选项

例子

databricks 捆绑包已打开

选项

例子

databricks 捆绑包运行

验证管道

传递作业参数

执行脚本

Arguments

选项

作业标志

作业任务标志

管道标志

例子

databricks 捆绑架构

选项

例子

databricks 捆绑包摘要

选项

例子

databricks 捆绑包同步

选项

例子

databricks 捆绑包验证

选项

例子

全局标志

其他資源

`bundle` 命令组