bundle 命令组

Note

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

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

Note

捆绑包命令在捆绑文件夹内运行时使用其中的设置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

    强制获取部署锁。 此选项禁用阻止并发部署相互交互的机制。 仅当上一个部署崩溃或中断并留下过时的锁定文件时，才应使用它。

--plan

    应用而非规划的 JSON 计划文件路径（仅限直接引擎）。 可以使用databricks bundle plan -o json创建计划文件。

全局标志

例子

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

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

databricks 捆绑包部署

与部署相关的命令。

databricks bundle deployment [command]

可用命令

• bind - 将捆绑定义的资源绑定到远程工作区中的现有资源。
• migrate - 迁移捆绑包以使用 直接部署引擎。
• unbind - 从其远程资源取消绑定捆绑定义的资源。

databricks 捆绑包部署绑定

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

databricks bundle deployment bind KEY RESOURCE_ID [flags]

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

绑定命令应与--target标记一起使用。 标识符格式取决于资源类型 — 请参阅以下 参数 。ß

Tip

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

以下资源支持绑定：

• app
• cluster
• dashboard
• job
• model_serving_endpoint
• pipeline
• quality_monitor
• registered_model
• schema
• volume

对于由 bundle generate 命令支持的资源，请使用 --bind 选项来在生成后自动绑定资源。

论据

KEY

    要绑定的资源的键

RESOURCE_ID

    要绑定到的现有资源的标识符。 格式取决于资源类型，因为绑定命令使用 GET REST API 终结点来发现资源。 对于由数字或 UUID 样式 ID（如作业和管道）标识的资源，请传递该 ID。 对于由其全名（如架构和卷）标识的 Unity 目录资源，请改为传递全名路径。 例如：

• 作业：数字 ID，例如 6565621249
• 管道：UUID，例如 7688611149d5709ac9-2900-1229-9996-586a9zez8929
• schema： full name in catalog.schema form， 例如 my_catalog.my_schema
• 卷：格式的完整 catalog.schema.volume 名称，例如 my_catalog.my_schema.my_volume
• registered_model：表单中的 catalog.schema.model 全名
• quality_monitor：窗体中 catalog.schema.table 的完整表名

选项

--auto-approve

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

--force-lock

    强制获取部署锁。 此选项禁用阻止并发部署相互交互的机制。 仅当上一个部署崩溃或中断并留下过时的锁定文件时，才应使用它。

全局标志

例子

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

databricks bundle deployment bind hello_job 6565621249

对于 Unity 目录资源（如架构和卷），请传递全名路径而不是 ID。 以下命令将捆绑定义的架构绑定到工作区中的现有架构：

databricks bundle deployment bind my_bundle_schema_ref my_existing_catalog.my_existing_schema

databricks 包部署迁移

Important

此功能目前以公共预览版提供。

从使用 Terraform 部署引擎迁移捆绑包到使用直接部署引擎。 请参阅 “迁移到直接部署引擎”。 若要完成迁移，必须部署捆绑包。

可以通过运行 databricks bundle plan验证迁移是否成功。 请参阅 databricks 捆绑计划。

databricks bundle deployment migrate [flags]

论据

None

选项

全局标志

例子

以下示例迁移当前捆绑包以使用 直接部署引擎：

databricks bundle deployment migrate

databricks 捆绑部署取消绑定

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

databricks bundle deployment unbind KEY [flags]

论据

KEY

    要取消绑定的资源的键

选项

--force-lock

    强制获取部署锁。 此选项禁用阻止并发部署相互交互的机制。 仅当上一个部署崩溃或中断并留下过时的锁定文件时，才应使用它。

全局标志

例子

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

databricks bundle deployment unbind hello_job

databricks 捆绑包销毁

Warning

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

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

databricks bundle destroy [flags]

Note

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

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

可以使用此设置 lifecycle 来防止特定资源被销毁。 请参阅 生命周期。

选项

--auto-approve

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

--force-lock

    强制获取部署锁。 此选项禁用阻止并发部署相互交互的机制。 仅当上一个部署崩溃或中断并留下过时的锁定文件时，才应使用它。

全局标志

例子

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

databricks bundle destroy

databricks 捆绑包生成

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

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

Important

bundle generate 命令为方便自动生成资源配置提供。 但是，如果捆绑包包含资源配置并部署它，Azure Databricks 会创建一个新资源，而不是更新现有资源。 若要更新现有资源，必须使用--bind参数与bundle generate一起，或在部署之前运行bundle deployment bind。 请参阅 databricks 捆绑部署绑定。

databricks bundle generate [command]

可用命令

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

选项

--key string

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

全局标志

databricks 捆绑包生成应用

为工作区中的现有 Databricks 应用生成捆绑配置。

databricks bundle generate app [flags]

选项

--bind

    将生成的资源与工作区中的现有资源自动绑定。

-d, --config-dir string

    将存储输出捆绑包配置的目录路径（默认“resources”）

--existing-app-name string

    要为其生成配置的应用名称

-f, --force

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

-s, --source-dir string

    将存储应用文件的目录路径（默认为“src/app”）

全局标志

例子

以下示例为名为 的现有应用生成配置。 可以从工作区 UI 的 “计算>应用 ”选项卡获取应用名称。

databricks bundle generate app --existing-app-name my-app

以下命令在hello_world.app.yml捆绑项目文件夹中生成一个新resources文件，并下载应用的代码文件，例如应用的命令配置文件和主app.yaml文件app.py。 默认情况下，代码文件将复制到捆绑包的文件夹 src 。

databricks bundle generate app --existing-app-name "hello_world"

# This is the contents of the resulting /resources/hello-world.app.yml file.
resources:
  apps:
    hello_world:
      name: hello-world
      description: A basic starter application.
      source_code_path: ../src/app

databricks 捆绑包生成仪表板

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

databricks bundle generate dashboard [flags]

Tip

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

选项

--bind

    将生成的资源与工作区中的现有资源自动绑定。

-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 复制仪表板的工作区路径。

例如，以下命令在baby_gender_by_county.dashboard.yml捆绑项目文件夹中生成包含以下 YAML 的新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 捆绑包生成作业

为作业生成捆绑配置。

Note

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

databricks bundle generate job [flags]

选项

--bind

    将生成的资源与工作区中的现有资源自动绑定。

-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 --bind

# 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]

Tip

如果您有现有的 Spark 声明性管道（SDP）项目，您可以使用 databricks pipelines generate 来生成其配置。 请参阅 databricks 管道生成。

选项

--bind

    将生成的资源与工作区中的现有资源自动绑定。

-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 bundle init

使用捆绑模板初始化新捆绑包。 可以将模板配置为提示用户输入值。 请参阅 声明性自动化捆绑包项目模板。

databricks bundle init [TEMPLATE_PATH] [flags]

论据

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 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 包方案

显示当前捆绑包配置的部署计划。

此命令生成捆绑包，并显示将在部署的资源上执行的操作，而无需进行任何更改。 这样，就可以在运行 bundle deploy之前预览更改。

databricks bundle plan [flags]

选项

-c, --cluster-id string

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

--force

    强制重写 Git 分支验证。

全局标志

例子

以下示例输出生成 Python 滚轮的捆绑包的部署计划，并定义作业和管道：

databricks bundle plan

Building python_artifact...
create jobs.my_bundle_job
create pipelines.my_bundle_pipeline

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

Note

如以下示例所示，可以使用作业任务选项将参数传递给作业任务，但 --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 统一身份验证。

论据

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]

Tip

你还可以使用 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 工作区中的目录。

Note

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!

Note

如果资源属性是在捆绑配置文件中定义的，而在相应对象的架构中找不到这些文件，则 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"