声明性自动化捆绑资源

声明性自动化捆绑包(以前称为 Databricks 资产捆绑包)允许指定捆绑包在捆绑配置中的 resources 映射中使用的Azure Databricks资源的相关信息。 请参阅 资源参考。

本页提供捆绑包支持的所有资源类型的配置参考,并提供了每个受支持类型的详细信息和示例。 有关其他示例,请参阅 捆绑包配置示例。

用于验证 YAML 配置的捆绑包的 JSON 架构位于 Databricks CLI GitHub存储库中。

Tip

若要为任何现有资源生成 YAML,请使用 databricks bundle generate 命令。 请参阅 databricks 捆绑包生成。

支持资源

下表列出了捆绑包(YAML 和 Python(如果适用)支持的资源类型。 可以通过在捆绑包中定义资源并部署捆绑包来创建一些资源,并且某些资源只能通过引用要包含在捆绑包中的现有资产来创建。

资源配置定义与 Databricks REST API 对象相对应的 Databricks 对象。 REST API 对象支持的创建请求字段(以 YAML 表示)是资源支持的密钥。 下表中提供了每个资源的相应对象的文档链接。

Tip

如果在捆绑包配置文件中发现未知的资源属性,databricks bundle validate 命令将返回警告。

Resource Python 支持 相应的 REST API 对象
警报 警报 警报对象
应用 应用 应用对象
目录 (Unity 目录) 目录 目录对象
星团 星团 集群对象
cluster_policy 集群政策 集群策略对象
仪表盘 仪表盘 仪表盘对象
database_catalog 数据库目录 数据库目录对象
database_instance 数据库实例 数据库实例对象
实验 实验 实验对象
external_location (Unity 目录) 外部地点 外部位置对象
功能 (Unity 目录) 特征
feature_spec (Unity 目录) 功能规格
genie_spaces Genie 空间 精灵代理人
instance_pool 实例池 实例池对象
工作 作业 作业对象
job_run 作业运行 作业运行对象
materialization_set 物质化集
mcp_service MCP服务 MCP服务对象
模型(遗产) 模型 模型(遗留)对象
model_provider_service 模型提供者服务 模型提供者服务对象
model_service 模型服务 模型服务对象
model_serving_endpoint 建模服务端点 建模服务端点对象
管道 管道 管道对象
postgres_branch Postgres 分支对象
postgres_catalog Postgres 目录对象
postgres_database Postgres 数据库对象
postgres_endpoint Postgres 计算端点对象
postgres_project Postgres 项目对象
postgres_role Postgres 角色对象
postgres_snapshot_schedule Postgres 快照调度对象
postgres_synced_table Postgres 同步表对象
quality_monitor 质量监测仪 质量监控对象
registered_model (Unity目录) 注册车型 注册模型对象
schema (Unity 目录) 模式 模式对象
secret (Unity 目录) 秘密 秘密对象
secret_scope 秘密瞄准镜 秘密范围对象
sql_warehouse SQL 仓库 SQL 仓库对象
synced_database_table 同步数据库表 同步数据库表对象
vector_search_endpoint 向量搜索端点 AI 搜索端点对象
vector_search_index 向量搜索索引 向量搜索索引对象
卷( Unity目录) 卷 体积对象

警报

Type: Map

警报资源定义 SQL 警报(v2)。

声明式自动化捆绑包的 Python 支持警报。 参见 databricks.bundles.alerts。

在Databricks CLI版本0.279.0中添加

alerts:
  <alert-name>:
    <alert-field-name>: <alert-field-value>
Key 类型 Description
custom_description String 可选。 警报的自定义说明。 根据 custom_template_format解释。
在Databricks CLI版本0.279.0中添加
custom_summary String 可选。 警报的自定义摘要。 根据 custom_template_format解释。
在Databricks CLI版本0.279.0中添加
custom_template_format String (测试版)解释和custom_description模板所使用的custom_summary格式。 有效值为:
  • HTML: 将这两个模板都当作带有 Mustache {{VARIABLE_NAME}} 占位符的 HTML。
  • MARKDOWN: 将这两个模板视为带有允许列表@VARIABLE_NAME占位符的 Markdown,并转换成每个通知目的地期望的格式,使单个模板在邮件、Slack 和 Microsoft Teams 中能够正确渲染。

如果未设置,两个模板都会渲染为 HTML。
在Databricks CLI版本1.21.0中添加
display_name String 必填。 警报的显示名称,例如 Example alert。
在Databricks CLI版本0.279.0中添加
evaluation Map 必填。 警报评估配置 请参阅 alert.evaluation。
在Databricks CLI版本0.279.0中添加
file_path String 警报资产的本地文件路径。
在Databricks CLI版本0.282.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.279.0中添加
parent_path String 可选。 包含警报的文件夹的工作区路径。 只能在创建时设置,不能更新。 示例:/Users/someone@example.com。
在Databricks CLI版本0.279.0中添加
permissions Sequence 警报权限。 查看 权限。
在Databricks CLI版本0.279.0中添加
query_text String 必填。 要运行的查询的文本,例如SELECT 1。
在Databricks CLI版本0.279.0中添加
run_as Map 可选。 指定用于运行警报的身份。 此字段允许将警报配置为作为特定用户或服务主体运行。 请参阅 run_as。
  • 对于用户标识:将user_name设置为活动工作区用户的电子邮件。 用户只能将其设置为自己的电子邮件。
  • 对于服务主帐户:将 service_principal_name 设为应用程序 ID。 需要拥有 servicePrincipal 或 user 角色。 如果未指定,警报将作为请求用户运行。

在Databricks CLI版本0.279.0中添加
schedule Map 必填。 警报的调度配置。 请参阅 alert.schedule。
在Databricks CLI版本0.279.0中添加
warehouse_id String 必填。 附加到警报的 SQL 仓库的 ID,例如a7066a8ef796be84。
在Databricks CLI版本0.279.0中添加

警报。评估

Type: Map

警报评估配置

Key 类型 Description
comparison_operator String 用于在警报评估中进行比较的运算符。
empty_result_state String 如果结果为空,则为警报状态。 避免将此字段设置为 UNKNOWN,因为 UNKNOWN 的状态计划弃用。
notification Map 当警报触发时需通知的用户或其他对象。 请参阅 alert.evaluation.notification。
source Map 用于评估警报的结果中的源列。 请参阅 alert.evaluation.source。
threshold Map 用于警报评估的阈值。 这可以是列或值。 请参阅 alert.evaluation.threshold。

警报。评估。通知

Type: Map

当警报触发时需通知的用户或其他对象。

Key 类型 Description
notify_on_ok 布尔 可选。 警报返回正常时是否通知警报订阅者。
retrigger_seconds Integer 可选。 警报在允许发送另一个通知之前触发后等待的秒数。 如果设置为 0 或省略,则警报不会在第一个触发器之后发送任何进一步通知。 设置此值为1可使警报在每次评估满足条件时发送通知,从而有效地使警报始终重新触发以进行通知。
subscriptions Sequence 可选。 通知订阅的无序列表。 请参阅 alert.evaluation.notification.subscriptions。
alert.evaluation.notification.subscriptions

Type: Sequence

无序的通知订阅列表。

列表中的每个项都是一个 AlertSubscription:

Key 类型 Description
destination_id String 通知目标的 ID。
user_email String 要通知的用户的电子邮件地址。

alert.evaluation.source

Type: Map

用于评估警报的结果中的源列。

Key 类型 Description
aggregation String 要应用于源列的聚合方法。 有效值为SUM、、COUNT、、COUNT_DISTINCTAVGMEDIAN、、 MINMAXSTDDEV
display String 源数据列的显示名称。
name String 查询结果中的源列的名称。

alert.evaluation.threshold

Type: Map

应用于警报评估的阈值可以是一个列或一个值。

Key 类型 Description
column Map 用于作为阈值的列引用。 请参阅 alert.evaluation.source。
value Map 要用作阈值的文本值。 请参阅 alert.evaluation.threshold.value。
alert.evaluation.threshold.value

Type: Map

要用作阈值的文本值。 指定以下值类型之一。

Key 类型 Description
bool_value 布尔 可选。 阈值的布尔值,例如 true。
double_value Double 可选。 阈值的数值,例如 1.25。
string_value String 可选。 阈值的字符串值,例如 test。

警报.日程

Type: Map

警报的调度配置。

Key 类型 Description
pause_status String 可选。 此计划是否处于暂停状态。 有效值: UNPAUSED, PAUSED。 默认值:UNPAUSED。
quartz_cron_schedule String 必填。 使用硅语法的 cron 表达式,指定此管道的计划。 Quartz 格式以 Quartz 调度器格式进行描述。
timezone_id String 必填。 Java时区 ID。计划将使用此时区解决。 这将与 quartz_cron_schedule 结合使用,以确定时间表。 有关详细信息,请参阅 SET TIME ZONE。

Examples

以下示例配置使用简单的评估定义警报:

resources:
  alerts:
    my_alert:
      display_name: my_alert
      evaluation:
        comparison_operator: EQUAL
        source:
          name: '1'
        threshold:
          value:
            double_value: 2
      query_text: select 2
      schedule:
        quartz_cron_schedule: '44 19 */1 * * ?'
        timezone_id: Europe/Amsterdam
      warehouse_id: 799f096837fzzzz4

以下示例配置定义了一个警报,其中包含使用聚合评估并发送通知的权限:

resources:
  alerts:
    my_alert:
      permissions:
        - level: CAN_MANAGE
          user_name: someone@example.com
      custom_summary: 'My alert'
      display_name: 'My alert'
      evaluation:
        comparison_operator: 'EQUAL'
        notification:
          notify_on_ok: false
          retrigger_seconds: 1
        source:
          aggregation: 'MAX'
          display: '1'
          name: '1'
        threshold:
          value:
            double_value: 2
      query_text: 'select 2'
      schedule:
        pause_status: 'UNPAUSED'
        quartz_cron_schedule: '44 19 */1 * * ?'
        timezone_id: 'Europe/Amsterdam'
      warehouse_id: 799f096837fzzzz4

应用

Type: Map

应用资源定义 Databricks 应用。 有关 Databricks 应用的信息,请参阅 Databricks Apps。

声明式自动化捆绑包的应用支持Python。 请参见 databricks.bundles.apps。

若要添加应用,请指定用于定义应用的设置,包括所需的 source_code_path设置。

Tip

可以使用以下命令通过 Streamlit Databricks 应用初始化捆绑包:

databricks bundle init https://github.com/databricks/bundle-examples --template-dir contrib/templates/streamlit-app

在Databricks CLI版本0.239.0中添加

apps:
  <app-name>:
    <app-field-name>: <app-field-value>
Key 类型 Description
budget_policy_id String 应用的预算策略 ID。
在Databricks CLI版本0.243.0中添加
compute_max_instances Integer 应用配置运行的最大应用实例数。 必须与 compute_min_instances一起设置。
在Databricks CLI版本1.2.0中添加
compute_min_instances Integer 应用配置运行的应用实例数量。 必须与 compute_max_instances一起设置。
在Databricks CLI版本1.2.0中添加
compute_size String 应用的计算大小。 有效值为 MEDIUM, LARGE或 XLARGE 取决于工作区配置。
新增于 Databricks CLI 版本 0.273.0
config Map 应用配置命令和环境变量。 请参阅 app.config。
在Databricks CLI版本0.283.0中添加
description String 应用的说明。
在Databricks CLI版本0.239.0中添加
git_repository Map 应用部署的 Git 存储库配置。 指定后,部署可以通过仅提供 git 引用(分支、标记或提交)来引用此存储库中的代码。 请参阅 app.git_repository。
在Databricks CLI版本0.283.0中添加
git_source Map 应用部署的 Git 源配置。 指定部署应用时要使用的 Git 引用(分支、标记或提交)。 与直接从 git 部署代码结合使用 git_repository 。 source_code_path内部git_source指定存储库中应用代码的相对路径。 请参阅 app.git_source。
在Databricks CLI版本0.290.0中添加
lifecycle Map 部署或销毁资源时的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 应用的名称。 名称必须仅包含小写字母数字字符和连字符。 在工作区中,它必须是唯一的。
在Databricks CLI版本0.239.0中添加
permissions Sequence 应用的权限。 查看 权限。
在Databricks CLI版本0.239.0中添加
resources Sequence 应用计算资源。 请参阅 app.resources。
在Databricks CLI版本0.239.0中添加
source_code_path String Databricks 应用源代码的 ./app 本地路径。
在Databricks CLI版本0.239.0中添加
space String (测试版)这个应用所属的空间名称。
在Databricks CLI版本0.290.0中添加
telemetry_export_destinations Sequence 应用的遥测导出目标。 请参阅 app.telemetry_export_destinations。
在Databricks CLI版本0.294.0中添加
usage_policy_id String 要用于此应用的无服务器使用策略的 ID。
在Databricks CLI版本0.283.0中添加
user_api_scopes Sequence 用户 API 范围。
在Databricks CLI版本0.246.0中添加

app.config

应用配置命令和环境变量。 请参阅使用 app.yaml 配置 Databricks 应用执行。

Key 类型 Description
command Sequence 用于运行应用的命令,例如 ["streamlit", "run", "app.py"]
env Sequence 指定要在应用运行时环境中设置的应用环境变量的列表 name 和 value 对。 这将替代 app.yaml 文件中指定的环境变量。 有关默认应用环境变量的信息,请参阅 Databricks Apps 环境。
在应用启动之前,不会设置环境变量。

app.git_repository

Type: Map

指定存储库位置的 Git 存储库配置。

Key 类型 Description
auto_deploy 布尔 当为真时,会在推送事件时自动部署应用到应用配置的 git_source分支。
在Databricks CLI版本1.14.0中添加
caller_credential_id Integer 调用者拥有的个人访问令牌 Git 凭证的 ID,用于授予应用服务主体访问该仓库的权限。
在Databricks CLI版本1.14.0中添加
provider String 必填。 Git 提供程序。 不区分大小写。 支持的值:gitHub、、gitHubEnterprise、bitbucketCloud、bitbucketServerazureDevOpsServices、gitLab、gitLabEnterpriseEdition、 awsCodeCommit。
在Databricks CLI版本0.283.0中添加
url String 必填。 Git 存储库的 URL。
在Databricks CLI版本0.283.0中添加

app.git_source

Type: Map

应用部署的 Git 源配置。

Key 类型 Description
branch String 要签出的 Git 分支。
commit String 要签出的 Git 提交 SHA。
source_code_path String Git 存储库中应用源代码的相对路径。 如果未指定,则使用存储库的根目录。
tag String 要签出的 Git 标记。

app.resources

Type: Sequence

应用的计算资源列表。

列表中的每个项都是一个 AppResource:

Key 类型 Description
app Map 应用名称和权限
description String 应用资源的说明。
database Map 标识要使用的 Lakebase 预配数据库的设置。 请参阅 app.resources.database。
experiment Map 标识要使用的 MLflow 试验的设置。 请参阅 app.resources.experiment。
genie_space Map 标识要使用的 Genie 代理的设置。 请参阅 app.resources.genie_space。
job Map 该设置用于标识要使用的作业资源。 请参阅 app.resources.job。
name String 应用资源的名称。
postgres Map 标识要使用的 Lakebase 自动缩放数据库的设置。 请参阅 app.resources.postgres。
secret Map 标识要使用的Azure Databricks机密资源的设置。 请参阅 app.resources.secret。
serving_endpoint Map 标识要使用的终结点资源的模型的设置。 请参阅 app.resources.serving_endpoint。
sql_warehouse Map 标识要使用的 SQL 仓库资源的设置。 请参阅 app.resources.sql_warehouse。
uc_securable Map 标识要使用的 Unity 目录安全对象的设置。 请参阅 app.resources.uc_securable。

app.resources.database。

Type: Map

标识要使用的 Lakebase 数据库的设置。

Key 类型 Description
database_name String 数据库的名称。
instance_name String 数据库实例的名称。
permission String 数据库的权限级别。 有效值为:CAN_CONNECT_AND_CREATE。

应用资源实验

Type: Map

标识要使用的 MLflow 试验的设置。

Key 类型 Description
experiment_id String MLflow 试验的 ID。
permission String 试验的权限级别。 有效值包括 CAN_READ, CAN_EDIT。 CAN_MANAGE

app.resources.genie_space

Type: Map

标识要使用的 Genie 代理的设置。

Key 类型 Description
name String Genie 代理的名称。
permission String 空间的权限级别。 有效值包括CAN_VIEW,,CAN_EDIT,CAN_MANAGECAN_RUN。
space_id String 例如 550e8400-e29b-41d4-a716-999955440000,Genie 代理的 ID。

app.resources.job。

Type: Map

该设置用于标识要使用的作业资源。

Key 类型 Description
id String 作业 ID。
permission String 作业的权限级别。 有效值包括CAN_VIEW,,CAN_MANAGE_RUN,CAN_MANAGEIS_OWNER。

app.resources.postgres

Type: Map

标识要使用的 Lakebase 自动缩放数据库的设置。

Key 类型 Description
branch String 例如 projects/proj-abc123/branches/branch-xyz789,分支的名称。
database String 例如 projects/proj-abc123/branches/branch-xyz789/databases/db-456,数据库实例的名称。
permission String 数据库的权限级别。 有效值为:CAN_CONNECT_AND_CREATE。

应用.resources.secret

Type: Map

标识要使用的Azure Databricks机密资源的设置。

Key 类型 Description
key String 用于授予权限的密钥。
permission String 机密的权限级别。 有效值包括 READ, WRITE。 MANAGE
scope String 机密范围的名称。

app.resources.serving_endpoint

Type: Map

标识要使用的终结点资源的模型的设置。

Key 类型 Description
name String 服务终结点的名称。
permission String 服务终结点的权限级别。 有效值包括 CAN_QUERY, CAN_MANAGE。 CAN_VIEW

app.resources.sql仓库

Type: Map

标识要使用的 SQL 仓库的设置。

Key 类型 Description
id String SQL 仓库的 ID。
permission String SQL 仓库的权限级别。 有效值包括 CAN_USE, CAN_MANAGE。 IS_OWNER

app.resources.uc_securable

Type: Map

标识要使用的 Unity 目录安全对象的设置。 应用支持卷、表、函数、连接和模型服务作为可保护的资源。

Key 类型 Description
permission String Unity 目录安全对象的权限级别。 有效值取决于 securable_type:
  • VOLUME: READ_VOLUME, WRITE_VOLUME
  • TABLE: SELECT, MODIFY
  • FUNCTION: EXECUTE
  • CONNECTION: USE_CONNECTION
  • MODEL_SERVICE: EXECUTE
securable_full_name String Unity 目录安全对象的全名,格式 catalog.schema.name为 。 对于连接,请使用连接名称。
securable_type String Unity 目录安全对象的类型。 有效值为 VOLUME、TABLE、FUNCTION、CONNECTION 和 MODEL_SERVICE。

Note

对于卷、表和函数,应用的服务主体还需要 USE CATALOG 对父目录和架构具有特权 USE SCHEMA 。 Azure Databricks将安全对象添加为应用资源时自动授予这些权限。

app.telemetry_export_destinations

Type: Sequence

应用的遥测导出目标列表。

在Databricks CLI版本0.294.0中添加

列表中的每个项都是一个 AppTelemetryExportDestination:

Key 类型 Description
unity_catalog Map 用于 TELEMETR 遥测导出的 Unity 目录目标。
在Databricks CLI版本0.294.0中添加

Examples

有关演示如何创建定义应用的捆绑包的教程,请参阅 使用声明性自动化捆绑包管理 Databricks 应用。

以下示例定义基本应用:

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

以下示例创建一个名为管理捆绑包创建的作业的应用 my_app 。 有关完整示例,请参阅 bundle-examples GitHub repository。

resources:
  jobs:
    # Define a job in the bundle
    hello_world:
      name: hello_world
      tasks:
        - task_key: task
          spark_python_task:
            python_file: ../src/main.py
          environment_key: default

      environments:
        - environment_key: default
          spec:
            environment_version: '2'

  # Define an app that manages the job in the bundle
  apps:
    job_manager:
      name: 'job_manager_app'
      description: 'An app which manages a job created by this bundle'

      # The location of the source code for the app
      source_code_path: ../src/app

      # The resources in the bundle which this app has access to. This binds the resource in the app with the bundle resource.
      resources:
        - name: 'app-job'
          job:
            id: ${resources.jobs.hello_world.id}
            permission: 'CAN_MANAGE_RUN'

相应的 app.yaml 定义用于运行应用的配置:

command:
  - flask
  - --app
  - app
  - run
  - --debug
env:
  - name: JOB_ID
    valueFrom: 'app-job'

以下示例创建有权访问捆绑包创建的 MLflow 试验的应用:

resources:
  experiments:
    # Define an MLflow experiment in the bundle
    my_experiment:
      name: /Users/${workspace.current_user.userName}/my-app-experiment

  apps:
    my_ml_app:
      name: 'my-ml-app'
      description: 'An app with access to an MLflow experiment'
      source_code_path: ./app

      # Grant the app access to the MLflow experiment
      resources:
        - name: 'app-experiment'
          experiment:
            experiment_id: ${resources.experiments.my_experiment.id}
            permission: 'CAN_MANAGE'

或者,以下示例使用捆绑配置中定义的自定义配置定义应用:

resources:
  apps:
    my_app:
      name: my_app
      description: my_app_description
      source_code_path: ./app
      config:
        command: ['flask', '--app', 'app', 'run']
        env:
          - name: MY_ENV_VAR
            value: test_value
          - name: ANOTHER_VAR
            value: another_value

以下示例使用 Lakebase 自动缩放资源定义应用:

resources:
  apps:
    my_app:
      name: my-app
      source_code_path: .
      resources:
        - name: lakebase-db
          postgres:
            branch: projects/my-app/branches/production
            database: projects/my-app/branches/production/databases/db-xxxx-yyyyyyyy
            permission: CAN_CONNECT_AND_CREATE

catalogs

Type: Map

目录资源允许在捆绑包中定义目录(Unity 目录)。

声明式自动化捆绑包的 Python 支持目录。 参见 databricks.bundles.catalogs。

Note

仅当使用 直接部署引擎时,才支持使用声明性自动化捆绑包来定义目录。

在Databricks CLI版本0.287.0中添加

catalogs:
  <catalog-name>:
    <catalog-field-name>: <catalog-field-value>
Key 类型 Description
comment String 用户提供的目录自由格式文本说明。
在Databricks CLI版本0.287.0中添加
connection_name String 与外部数据源的连接的名称。
在Databricks CLI版本0.287.0中添加
custom_max_retention_hours Integer 目录的最大保留时间为小时。
在Databricks CLI 1.5.0版本中添加
grants Sequence 与目录关联的授予。 请参阅 授予。
在Databricks CLI版本0.287.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.287.0中添加
managed_encryption_settings Map 控制托管目录数据的 CMK 加密。 请参阅 catalog.managed_encryption_settings。
新增于 Databricks CLI 版本 0.298.0
name String 必填。 目录的名称。
在Databricks CLI版本0.287.0中添加
options 物体 附加到安全对象的键值属性的映射。
在Databricks CLI版本0.287.0中添加
properties 物体 附加到安全对象的键值属性的映射。
在Databricks CLI版本0.287.0中添加
provider_name String OpenSharing 提供程序的名称。 OpenSharing 目录是基于远程共享服务器上的 OpenSharing 共享的目录。 请参阅 什么是 OpenSharing?。
在Databricks CLI版本0.287.0中添加
share_name String 共享提供程序下共享的名称。
在Databricks CLI版本0.287.0中添加
storage_root String 目录中托管表的存储根 URL。
在Databricks CLI版本0.287.0中添加

Example

# databricks.yml
bundle:
  name: catalogs-example
  engine: direct # catalogs require the direct deployment engine

resources:
  catalogs:
    my_catalog:
      name: my_catalog
      comment: 'Catalog created by Declarative Automation Bundles'
      properties:
        purpose: 'Testing'
      grants:
        - principal: someone@example.com
          privileges:
            - USE_CATALOG
            - CREATE_SCHEMA

  schemas:
    my_schema:
      name: my_schema
      catalog_name: ${resources.catalogs.my_catalog.name}
      comment: 'Schema in custom catalog'

catalog.managed_encryption_settings

Type: Map

托管目录数据的加密设置。 用于配置客户管理的密钥(CMK)。

新增于 Databricks CLI 版本 0.298.0

Key 类型 Description
azure_encryption_settings Map 可选Azure设置 - 仅当使用 Azure CMK 时才是必需的。
新增于 Databricks CLI 版本 0.298.0
azure_key_vault_key_id String Azure中的 AKV URL,否则为 null。
新增于 Databricks CLI 版本 0.298.0
customer_managed_key_id String 否则,AWS 和 GCP 中的 CMK UUID 为 null。
新增于 Databricks CLI 版本 0.298.0

星团

Type: Map

群集资源定义 群集。

Python 声明式自动化捆包支持集群。 参见 databricks.bundles.clusters。

clusters:
  <cluster-name>:
    <cluster-field-name>: <cluster-field-value>
Key 类型 Description
apply_policy_default_values 布尔 设置为 true 时,策略中的固定值和默认值将用于省略的字段。 设置为 false 时,将仅应用策略中的固定值。
autoscale Map 为了根据负载自动纵向扩展和缩减群集所需的参数。 请参阅 autoscale。
autotermination_minutes Integer 在群集处于非活动状态(以分钟为单位)后自动终止群集。 如果未设置,则不会自动终止此群集。 如果指定,阈值必须介于 10 到 10000 分钟之间。 用户还可以将此值设置为 0 以显式禁用自动终止。
aws_attributes Map 与 Amazon Web Services 上运行的群集相关的属性。 如果未在创建群集时指定,将使用一组默认值。 请参阅 aws_attributes。
azure_attributes Map 与在 Microsoft Azure 上运行的群集相关的属性。 如果未在创建群集时指定,将使用一组默认值。 请参阅 azure_attributes。
cluster_log_conf Map 用于将 Spark 日志传送到长期存储目标的配置。 请参阅 cluster_log_conf。
cluster_name String 用户请求的群集名称。 这不必是唯一的。 如果未在创建时指定,群集名称将为空字符串。
custom_tags Map 群集资源的其他标记。 除了 default_tags,Databricks 还会使用这些标记来标记所有群集资源(例如,AWS 实例和 EBS 卷)。
data_security_mode String 从群集访问数据时要使用的数据治理模型。 有效值包括 DATA_SECURITY_MODE_AUTO、DATA_SECURITY_MODE_STANDARD、DATA_SECURITY_MODE_DEDICATED和 NONE。 USER_ISOLATION和SINGLE_USER分别是和DATA_SECURITY_MODE_DEDICATED的遗留别名DATA_SECURITY_MODE_STANDARD。 从 Databricks Runtime 15.0 开始,模式 LEGACY_* 已弃用。
dependency_mode String (测试版)控制集群的依赖配置。 有效值为:DEPENDENCY_MODE_ENVIRONMENTS、DEPENDENCY_MODE_CLUSTER_LIBRARIES 和 DEPENDENCY_MODE_AUTO。
在Databricks CLI版本1.10.0中添加
docker_image Map 自定义 Docker 映像。 请参阅 docker_image。
driver_instance_pool_id String 群集所属的驱动程序实例池的可选 ID。 如果未分配驱动程序池,池群集将使用 ID 为 (instance*pool_id) 的实例池。
driver_node_type_flexibility Map 驱动程序节点的灵活节点类型配置。 请参阅 cluster.driver_node_type_flexibility。
在Databricks CLI版本0.285.0中添加
driver_node_type_id String Spark 驱动程序的节点类型。 此字段可选。 如果未设置,驱动程序节点类型将设置为值 node_type_id。
enable_elastic_disk 布尔 自动缩放本地存储:启用后,当 Spark 辅助角色在磁盘空间不足时,此群集将动态获取额外的磁盘空间。 此功能需要特定的 AWS 权限才能正常运行 - 有关详细信息,请参阅用户指南。
enable_local_disk_encryption 布尔 是否在群集 VM 的本地磁盘上启用 LUKS。
gcp_attributes Map 与 Google Cloud Platform 上运行的群集相关的属性。 如果未在创建群集时指定,将使用一组默认值。 请参阅 gcp_attributes。
init_scripts Sequence 用于存储初始化脚本的配置。 可以指定任意数量的目标。 这些脚本会按照所提供的顺序依次执行。 请参阅 init_scripts。
instance_pool_id String 群集所属的实例池的可选 ID。
is_single_node 布尔 仅在满足kind = CLASSIC_PREVIEW条件时才能使用此字段。 设置为 true 时,Databricks 将自动设置单个节点相关 custom_tags, spark_conf以及 num_workers。
在Databricks CLI版本0.237.0中添加
kind String 此计算规范描述的计算类型。
在Databricks CLI版本0.237.0中添加
libraries Sequence 一份需要安装在集群上的库列表。 在创建集群后通过库API安装。 参见 cluster.libraries。
在Databricks CLI版本1.19.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
node_type_id String 此字段通过单个值对提供给此群集中的每个 Spark 节点的资源进行编码。 例如,可以针对内存或计算密集型工作负载对 Spark 节点进行预配和优化。 可以使用 列表节点类型 API 检索可用节点类型的列表。
num_workers Integer 此群集应该拥有的工作器节点的数目。 群集有一个 Spark 驱动器和 num_workers 执行器,总共 num_workers + 1 个 Spark 节点。
permissions Sequence 群集权限。 查看 权限。
policy_id String 用于创建群集(如果适用)的群集策略的 ID。
remote_disk_throughput Integer 每秒远程磁盘吞吐量(以字节为单位)。
在Databricks CLI版本0.257.0中添加
runtime_engine String 确定群集的运行时引擎是 STANDARD 或 PHOTON。
single_user_name String 如果 data*security_mode 为 SINGLE_USER,则为单个用户名。
spark_conf Map 一个对象,其中包含一组可选的由用户指定的 Spark 配置键值对。 用户还可以通过spark.driver.extraJavaOptions和spark.executor.extraJavaOptions分别传入驱动程序和执行程序的额外 JVM 选项字符串。
spark_env_vars Map 一个对象,其中包含一组可选的由用户指定的环境变量键值对。
spark_version String 群集的 Spark 版本,例如 3.3.x-scala2.11 可以使用 列表可用的 Spark 版本 API 检索可用的 Spark 版本列表。
ssh_public_keys Sequence 将会添加到此群集中各个 Spark 节点的 SSH 公钥内容。 相应的私钥可用于在端口ubuntu上使用用户名2200登录。 最多可以指定 10 个密钥。
total_initial_remote_disk_size Integer 如果设置好,远程磁盘的初始总卷大小(以GB计)应是多少。 支持GCP。
在Databricks CLI版本0.257.0中添加
use_ml_runtime 布尔 仅在满足kind = CLASSIC_PREVIEW条件时才能使用此字段。 effective_spark_version由(Databricks运行时发布)、该字段use_ml_runtime、以及是否node_type_id为GPU节点决定spark_version。
在Databricks CLI版本0.237.0中添加
worker_node_type_flexibility Map 辅助角色节点的灵活节点类型配置。 请参阅 cluster.worker_node_type_flexibility。
在Databricks CLI版本0.285.0中添加
workload_type Map 显示群集工作负荷类型的群集属性。 请参阅 workload_type。

cluster.libraries

Type: Sequence

一份需要安装在集群上的库列表。 在创建集群后通过库API安装。

在Databricks CLI版本1.19.0中添加

列表中的每一项都是一个Library:

Key 类型 Description
cran Map 指定安装一个CRAN库作为库的一部分。
在Databricks CLI版本0.229.0中添加
jar String 要安装的 JAR 库的 URI。 支持的 URI 包括工作区路径、Unity 目录卷路径和 S3 URI。 例如:{ "jar": "/Workspace/path/to/library.jar" }、{ "jar" : "/Volumes/path/to/library.jar" }或{ "jar": "s3://my-bucket/library.jar" }。 如果使用 S3,确保集群在库中拥有读取权限。 你可能需要用IAM角色启动集群才能访问S3 URI。
在Databricks CLI版本0.229.0中添加
maven Map 需要安装的 Maven 库规范。 例如: { "coordinates": "org.jsoup:jsoup:1.7.2" }。
在Databricks CLI版本0.229.0中添加
pypi Map 需安装的 PyPI 库规范。 例如: { "package": "simplejson" }。
在Databricks CLI版本0.229.0中添加
requirements String 要安装的 requirements.txt 文件的 URI。 仅支持工作区路径和 Unity 目录卷路径。 例如: { "requirements": "/Workspace/path/to/requirements.txt" } 或 { "requirements" : "/Volumes/path/to/requirements.txt" } 。
在Databricks CLI版本0.229.0中添加
whl String 要安装的 wheel 库的 URI。 支持的 URI 包括工作区路径、Unity 目录卷路径和 S3 URI。 例如:{ "whl": "/Workspace/path/to/library.whl" }、{ "whl" : "/Volumes/path/to/library.whl" }或{ "whl": "s3://my-bucket/library.whl" }。 如果使用 S3,确保集群在库中拥有读取权限。 你可能需要用IAM角色启动集群才能访问S3 URI。
在Databricks CLI版本0.229.0中添加

cluster.autoscale

Type: Map

用于根据负载自动纵向扩展和缩减群集的参数。

Key 类型 Description
min_workers Integer 群集在未充分利用时可缩减到的最小辅助角色数。 这也是群集在创建后将具有的初始辅助角色数。
max_workers Integer 群集在重载时可以纵向扩展的最大辅助角色数。 max_workers 必须严格大于 min_workers。

cluster.aws_attributes

Type: Map

与 Amazon Web Services 上运行的群集相关的属性。

Key 类型 Description
zone_id String 群集所在的可用性区域/数据中心的标识符。 此字符串的格式如下 us-west-2a。
availability String 用于在 first_on_demand 节点之后的所有节点的可用性类型。 有效值为 SPOT, ON_DEMANDSPOT_WITH_FALLBACK。 如果 first_on_demand 为零,则该可用性类型用于整个集群。
spot_bid_price_percent Integer AWS Spot 实例的最大价格,占对应实例类型按需价格的百分比。
instance_profile_arn String 此群集的节点将仅放置在具有此实例配置文件的 AWS 实例上。
first_on_demand Integer 群集的第一个 first_on_demand 节点将放置在按需实例上。 此值应大于 0,以确保将群集驱动程序节点放置在按需实例上。
ebs_volume_type String 将使用此群集启动的 EBS 卷的类型。 有效值为 GENERAL_PURPOSE_SSD 或 THROUGHPUT_OPTIMIZED_HDD。
ebs_volume_count Integer 每个实例创建的卷数。
ebs_volume_size Integer 为每个实例启动的每个 EBS 卷(以 GiB 为单位)的大小。
ebs_volume_iops Integer 每个 EBS gp3 卷的 IOPS 数。
ebs_volume_throughput Integer 每个 EBS gp3 卷的吞吐量(以 MiB/秒为单位)。

cluster.azure_attributes

Type: Map

与在 Microsoft Azure 上运行的群集相关的属性。

Key 类型 Description
first_on_demand Integer 群集的第一个 first_on_demand 节点将放置在按需实例上。
availability String 用于在 first_on_demand 节点之后的所有节点的可用性类型。 有效值为 SPOT_AZURE, ON_DEMAND_AZURESPOT_WITH_FALLBACK_AZURE。 如果 first_on_demand 为零,则该可用性类型用于整个集群。
spot_bid_max_price 编号 Azure现成实例的最大价格。 使用 -1 指定最低价格。
capacity_reservation_group String 用于启动虚拟机的Azure容量预留组资源ID,格式为 /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{capacityReservationGroupName}。 指定后,虚拟机会根据提供的容量预留启动。
只有当工作区使用注入的VNet(客户定义的VNet,未由Databricks管理)时,才能指定容量预留。 databricks-login-prod企业应用必须获得以下四个权限:Microsoft.Compute/capacityReservationGroups/read、、 Microsoft.Compute/capacityReservationGroups/deploy/actionMicrosoft.Compute/capacityReservationGroups/capacityReservations/read和 Microsoft.Compute/capacityReservationGroups/capacityReservations/deploy/action。
在Databricks CLI 1.5.0版本中添加
log_analytics_info Map Azure Log Analytics代理的配置。 请参阅 log_analytics_info。

cluster.azure_attributes.log_analytics_info

Type: Map

Azure Log Analytics代理的配置。

Key 类型 Description
log_analytics_workspace_id String Azure Log Analytics工作区的 ID。
log_analytics_primary_key String Azure Log Analytics工作区的主键。

cluster.gcp_attributes

Type: Map

与 Google Cloud Platform 上运行的群集相关的属性。

Key 类型 Description
use_preemptible_executors 布尔 是否使用抢占执行器。 GCE 抢占执行程序是可随时被 GCE 回收的抢占实例。
google_service_account String Databricks 群集 VM 实例使用的 Google 服务帐户。
local_ssd_count Integer 要为集群中每个节点附加的本地 SSD 的数量。 默认值为 0。
zone_id String 群集所在的可用性区域/数据中心的标识符。
availability String 确定 Spark 执行器是被安排在可抢占虚拟机、按需虚拟机,还是在不可用时备份到按需虚拟机的抢占虚拟机上运行。 有效值为 PREEMPTIBLE_GCP, ON_DEMAND_GCPPREEMPTIBLE_WITH_FALLBACK_GCP。
boot_disk_size Integer 启动磁盘的大小(以 GB 为单位)。 值通常范围为 100 到 1000。

cluster.cluster_log_conf

用于将 Spark 日志传送到长期存储目标的配置。

Key 类型 Description
dbfs Map 群集日志传递的 DBFS 位置。 请参阅 dbfs。
s3 Map 群集日志传输的 S3 位置。 请参阅 s3。
volumes Map 用于群集日志传送的卷的位置。 请参阅 卷。

cluster.cluster_log_conf.dbfs

Type: Map

群集日志传递的 DBFS 位置。

Key 类型 Description
destination String 群集日志传递的 DBFS 路径(例如, dbfs:/cluster-logs)。

cluster.cluster_log_conf.s3

Type: Map

群集日志传输的 S3 位置。

Key 类型 Description
destination String 群集日志传递的 S3 URI(例如,s3://my-bucket/cluster-logs)。
region String S3 存储桶的 AWS 区域。
endpoint String S3 终结点 URL(可选)。
enable_encryption 布尔 是否为群集日志启用加密。
encryption_type String 加密类型。 有效值包括 SSE_S3,SSE_KMS.
kms_key String 用于加密的 KMS 密钥 ARN(当使用 SSE_KMS 时)。
canned_acl String 要应用于群集日志的预定义 ACL。

cluster.cluster_log_conf卷

Type: Map

用于群集日志传送的卷的位置。

Key 类型 Description
destination String 群集日志传送的卷路径(例如, /Volumes/catalog/schema/volume/cluster_log)。

cluster.docker_image

Type: Map

自定义 Docker 映像配置。

Key 类型 Description
url String Docker 映像的 URL。
basic_auth Map Docker 存储库的基本身份验证。 请参阅 basic_auth。

cluster.docker_image.basic_auth

Type: Map

Docker 存储库的基本身份验证。

Key 类型 Description
username String Docker 注册表身份验证的用户名。
password String Docker 注册表身份验证的密码。

cluster.init_scripts

Type: Map

用于存储初始化脚本的配置。 必须至少指定一个位置类型。

Key 类型 Description
dbfs Map init 脚本的 DBFS 位置。 请参阅 dbfs。
workspace Map init 脚本的工作区位置。 请参阅 workspace。
s3 Map 初始化脚本的 S3 位置。 请参阅 s3。
abfss Map init 脚本的 ABFSS 位置。 请参阅 abfss。
gcs Map init 脚本的 GCS 位置。 请参阅 gcs。
volumes Map init 脚本的 Unity 目录卷位置。 请参阅 卷。

cluster.init_scripts.dbfs

Type: Map

init 脚本的 DBFS 位置。

Key 类型 Description
destination String init 脚本的 DBFS 路径。

cluster.init_scripts.workspace

Type: Map

init 脚本的工作区位置。

Key 类型 Description
destination String init 脚本的工作区路径。

cluster.init_scripts.s3

Type: Map

初始化脚本的 S3 位置。

Key 类型 Description
destination String init 脚本的 S3 URI。
region String S3 存储桶的 AWS 区域。
endpoint String S3 终结点 URL(可选)。

cluster.init_scripts.abfsss

Type: Map

init 脚本的 ABFSS 位置。

Key 类型 Description
destination String 初始化脚本的 ABFSS 路径。

cluster.init_scripts.gcss

Type: Map

init 脚本的 GCS 位置。

Key 类型 Description
destination String init 脚本的 GCS 路径。

cluster.init_scripts卷

Type: Map

init 脚本的卷位置。

Key 类型 Description
destination String init 脚本的 Unity 目录卷路径。

cluster.driver_node_type_flexibility

Type: Map

驱动程序节点的灵活节点类型配置。

在Databricks CLI版本0.285.0中添加

Key 类型 Description
alternate_node_type_ids Sequence 当主节点类型不可用时用作回退的节点类型 ID 的列表。
在Databricks CLI版本0.285.0中添加
aws_context_id String EC2车队的AWS上下文ID。 当设置为非空时,该值会传递给AWS CreateFleet API,以创建EC2舰队。
在Databricks CLI版本1.16.0中添加

cluster.worker_node_type_flexibility

Type: Map

辅助角色节点的灵活节点类型配置。

在Databricks CLI版本0.285.0中添加

Key 类型 Description
alternate_node_type_ids Sequence 当主节点类型不可用时用作回退的节点类型 ID 的列表。
在Databricks CLI版本0.285.0中添加
aws_context_id String EC2车队的AWS上下文ID。 当设置为非空时,该值会传递给AWS CreateFleet API,以创建EC2舰队。
在Databricks CLI版本1.16.0中添加

cluster.workload_type

Type: Map

显示群集工作负荷类型的群集属性。

Key 类型 Description
clients Map 定义客户端可以使用群集的类型。 请参阅 客户端。

cluster.workload_type.client

Type: Map

此计算工作负荷的客户端类型。

Key 类型 Description
jobs 布尔 群集是否可以运行作业。
notebooks 布尔 群集是否可以运行笔记本。

Examples

以下示例使用 Databricks Runtime 15.4 LTS 和群集策略为当前用户创建专用(单用户)群集:

resources:
  clusters:
    my_cluster:
      num_workers: 0
      node_type_id: 'i3.xlarge'
      driver_node_type_id: 'i3.xlarge'
      spark_version: '15.4.x-scala2.12'
      spark_conf:
        'spark.executor.memory': '2g'
      autotermination_minutes: 60
      enable_elastic_disk: true
      single_user_name: ${workspace.current_user.userName}
      policy_id: '000128DB309672CA'
      enable_local_disk_encryption: false
      data_security_mode: SINGLE_USER
      runtime_engine: STANDARD

此示例创建一个简单的群集 my_cluster ,并将其设置为用于运行笔记本的 my_job群集:

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: 'i3.xlarge'
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: '13.3.x-scala2.12'
      spark_conf:
        'spark.executor.memory': '2g'

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          notebook_task:
            notebook_path: './src/my_notebook.py'
          existing_cluster_id: ${resources.clusters.my_cluster.id}

cluster_policy

Type: Map

集群策略资源定义了一个集群 策略 ,限制基于一套规则配置集群的能力。

声明式自动化捆绑包的 Python 支持集群策略。 请参见 databricks.bundles.cluster_policies。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义集群策略。

在Databricks CLI版本1.14.0中添加

cluster_policies:
  <cluster_policy-name>:
    <cluster_policy-field-name>: <cluster_policy-field-value>
Key 类型 Description
definition String 以 Databricks集群策略定义语言表达的策略定义文档。
在Databricks CLI版本1.14.0中添加
description String 群集策略的其他可读说明。
在Databricks CLI版本1.14.0中添加
libraries Sequence 下一次集群重启时使用该策略将安装的库列表。 图书馆最多可达500个。 参见 cluster_policy.libraries。
在Databricks CLI版本1.14.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.14.0中添加
max_clusters_per_user Integer 每个用户可以使用此策略的最大群集数。 如果不存在,则没有最高限额。
在Databricks CLI版本1.14.0中添加
name String 用户请求的群集策略名称。 这必须是独一无二的。 长度必须介于 1 到 100 个字符之间。
在Databricks CLI版本1.14.0中添加
permissions Sequence 集群策略权限。 集群策略只支持权限 CAN_USE 级别。 查看 权限。
在Databricks CLI版本1.14.0中添加
policy_family_definition_overrides String 以 Databricks策略定义语言表达的策略定义JSON文档。 JSON 文档必须以字符串形式传递,不能嵌入请求中。
你可以利用它自定义继承自保单家族的保单定义。 这里指定的策略规则合并进继承的策略定义中。
在Databricks CLI版本1.14.0中添加
policy_family_id String 策略系列的 ID。 集群策略的策略定义继承了策略家族的策略定义。 不能与 definition 一起使用。 改用 policy_family_definition_overrides 它来自定义策略定义。
在Databricks CLI版本1.14.0中添加

cluster_policy.libraries

Type: Sequence

下一次集群重启时使用该策略将安装的库列表。 图书馆最多可达500个。

列表中的每一项都是一个Library:

Key 类型 Description
cran Map 指定安装一个CRAN库作为库的一部分。
在Databricks CLI版本0.229.0中添加
jar String 要安装的 JAR 库的 URI。 支持的 URI 包括工作区路径、Unity 目录卷路径和 S3 URI。 例如:{ "jar": "/Workspace/path/to/library.jar" }、{ "jar" : "/Volumes/path/to/library.jar" }或{ "jar": "s3://my-bucket/library.jar" }。 如果使用 S3,确保集群在库中拥有读取权限。 你可能需要用IAM角色启动集群才能访问S3 URI。
在Databricks CLI版本0.229.0中添加
maven Map 需要安装的 Maven 库规范。 例如: { "coordinates": "org.jsoup:jsoup:1.7.2" }。
在Databricks CLI版本0.229.0中添加
pypi Map 需安装的 PyPI 库规范。 例如: { "package": "simplejson" }。
在Databricks CLI版本0.229.0中添加
requirements String 要安装的 requirements.txt 文件的 URI。 仅支持工作区路径和 Unity 目录卷路径。 例如: { "requirements": "/Workspace/path/to/requirements.txt" } 或 { "requirements" : "/Volumes/path/to/requirements.txt" } 。
在Databricks CLI版本0.229.0中添加
whl String 要安装的 wheel 库的 URI。 支持的 URI 包括工作区路径、Unity 目录卷路径和 S3 URI。 例如:{ "whl": "/Workspace/path/to/library.whl" }、{ "whl" : "/Volumes/path/to/library.whl" }或{ "whl": "s3://my-bucket/library.whl" }。 如果使用 S3,确保集群在库中拥有读取权限。 你可能需要用IAM角色启动集群才能访问S3 URI。
在Databricks CLI版本0.229.0中添加

Example

以下示例定义了集群策略,并授予组使用该策略的权限:

# databricks.yml
bundle:
  name: cluster-policies-example
  engine: direct # Cluster policies require the direct deployment engine

resources:
  cluster_policies:
    my_policy:
      name: my-cluster-policy
      description: Standard policy for team clusters
      max_clusters_per_user: 5
      definition: |
        {
          "spark_version": {
            "type": "fixed",
            "value": "15.4.x-scala2.12"
          },
          "autotermination_minutes": {
            "type": "range",
            "maxValue": 120
          }
        }
      permissions:
        - level: CAN_USE
          group_name: data-engineers

仪表盘

Type: Map

仪表板资源允许你在捆绑包中管理 AI/BI 仪表板 。 有关 AI/BI 仪表板的信息,请参阅 仪表板。

Python 支持声明式自动化捆绑包的仪表盘。 参见 databricks.bundles.dashboards。

如果您部署了一个捆绑包,其中包含本地环境中的仪表板,然后使用 UI 修改该仪表板,则通过 UI 进行的修改不会应用在本地捆绑包中的仪表板 JSON 文件上,除非您使用 bundle generate 显式更新该文件。 可以使用 --watch 选项持续轮询和检索仪表板的更改。 请参阅 databricks 捆绑包生成。

此外,如果尝试从本地环境部署包含与远程工作区中的仪表板 JSON 文件不同版本的仪表板 JSON 文件的捆绑包,则会发生错误。 若要强制部署并用本地工作区的仪表板覆盖远程工作区中的仪表板,请使用 --force 选项。 请参阅 databricks 捆绑包部署。

在Databricks CLI版本0.232.0中添加

Note

将声明性自动化捆绑包与 仪表板 Git 支持配合使用时,通过添加 同步映射 来阻止生成重复的仪表板,以排除仪表板以文件同步:

sync:
  exclude:
    - src/*.lvdash.json
dashboards:
  <dashboard-name>:
    <dashboard-field-name>: <dashboard-field-value>
Key 类型 Description
dataset_catalog String 仪表板中所有数据集使用的默认目录值(如果未在查询中指定)。 有关设置此字段的示例配置,请参阅 仪表板目录和架构参数化。
在Databricks CLI版本0.283.0中添加
dataset_schema String 仪表板中所有数据集使用的默认架构值(如果未在查询中指定)。 有关设置此字段的示例配置,请参阅 仪表板目录和架构参数化。
在Databricks CLI版本0.283.0中添加
display_name String 仪表板的显示名称。
在Databricks CLI版本0.232.0中添加
embed_credentials 布尔 捆绑包部署标识凭据是否用于为所有仪表板查看器执行查询。 如果设置为 false,则使用查看者的凭据。 默认值为 false。
在Databricks CLI版本0.232.0中添加
etag String 仪表板的实体标记。 可以在更新时选择提供,以确保自上次读取以来仪表板未被修改。
在Databricks CLI版本0.234.0中添加
file_path String 仪表板资产的本地路径,包括文件名。 导出的仪表板始终具有文件扩展名 .lvdash.json。
在Databricks CLI版本0.232.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
parent_path String 包含仪表板的文件夹的工作区路径。 包括前导斜杠和无尾部斜杠。
在Databricks CLI版本0.232.0中添加
path String 仪表板资产的工作区路径,包括资产名称。
在Databricks CLI版本0.234.0中添加
permissions Sequence 仪表板权限。 查看 权限。
在Databricks CLI版本0.232.0中添加
serialized_dashboard Any 以序列化字符串形式表示的仪表板的内容。
在Databricks CLI版本0.232.0中添加
warehouse_id String 用于运行仪表板的仓库 ID。
在Databricks CLI版本0.232.0中添加

Example

以下示例包含在 Databricks 工作区中部署 NYC 出租车行程分析 仪表板的步骤。

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: 'NYC Taxi Trip Analysis'
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

database_catalog

Type: Map

使用数据库目录资源可以定义与捆绑包中的数据库实例对应的 数据库目录 。 数据库目录是注册为 Unity 目录的 Lakebase 数据库。

对于新工作负载,Databricks 推荐使用该 postgres_catalogs 资源。

声明式自动化捆绑包的 Python 支持数据库目录。 请看 databricks.bundles.database_catalogs。

有关数据库目录的信息,请参见 “注册数据库”。

在Databricks CLI版本0.265.0中添加

database_catalogs:
  <database_catalog-name>:
    <database_catalog-field-name>: <database_catalog-field-value>
Key 类型 Description
create_database_if_not_exists 布尔 如果数据库不存在,则是否创建数据库。
在Databricks CLI版本0.265.0中添加
database_instance_name String 包含数据库的实例的名称。
在Databricks CLI版本0.265.0中添加
database_name String 数据库名称(实例中)与目录相关。
在Databricks CLI版本0.265.0中添加
lifecycle Map 包含资源的生命周期设置,包括部署或销毁资源时资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.265.0中添加
name String Unity 目录中目录的名称。
在Databricks CLI版本0.265.0中添加

Example

以下示例使用相应的数据库目录定义 数据库实例 :

resources:
  database_instances:
    my_instance:
      name: my-instance
      capacity: CU_1
  database_catalogs:
    my_catalog:
      database_instance_name: ${resources.database_instances.my_instance.name}
      name: example_catalog
      database_name: my_database
      create_database_if_not_exists: true

database_instance

Type: Map

通过数据库实例资源,可以在捆绑包中定义 数据库实例 。 Lakebase 数据库实例管理存储和计算资源,并提供用户连接到的终结点。

声明式自动化捆绑包的 Python 支持数据库实例。 请参见 databricks.bundles.database_instances。

Note

资源创建 database_instances 的新数据库实例现在创建为 Lakebase 自动缩放项目。 有关详细信息,请参阅 默认情况下的自动缩放 。 对于新的Lakebase工作,Databricks推荐使用该 postgres_projects 资源。

重要

使用数据库实例部署捆绑包时,该实例会立即开始运行,并受定价约束。 请参阅 Lakebase 定价。

有关数据库实例的信息,请参阅 Lakebase Provisioned。

在Databricks CLI版本0.265.0中添加

database_instances:
  <database_instance-name>:
    <database_instance-field-name>: <database_instance-field-value>
Key 类型 Description
capacity String 实例的 SKU。 有效值为 CU_1,, CU_2CU_4。 CU_8
在Databricks CLI版本0.265.0中添加
custom_tags Sequence 指定与实例关联的自定义标签的键值对列表。
新增于 Databricks CLI 版本 0.273.0
enable_pg_native_login 布尔 实例是否启用了 PG 本机密码登录。 默认为 true。
在Databricks CLI版本0.267.0中添加的
enable_readable_secondaries 布尔 是否启用辅助数据库来提供只读流量。 默认为 false。
在Databricks CLI版本0.265.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 实例的名称。 这是实例的唯一标识符。
在Databricks CLI版本0.265.0中添加
node_count Integer 实例中的节点数,由 1 个主节点和 0 个或多个辅助数据库组成。 默认为 1 个主副本和 0 个辅助数据库。
在Databricks CLI版本0.265.0中添加
parent_instance_ref Map 父实例的引用。 仅当实例为子实例时,此实例才可用。 请参阅 父实例。
在Databricks CLI版本0.265.0中添加
permissions Sequence 数据库实例的权限。 查看 权限。
在Databricks CLI版本0.265.0中添加
retention_window_in_days Integer 实例的保留时段。 这是保留历史数据的时间范围(以天为单位)。 默认值为 7 天。 有效值为 2 到 35 天。
在Databricks CLI版本0.265.0中添加
stopped 布尔 实例是否已停止。
在Databricks CLI版本0.265.0中添加
usage_policy_id String 要与实例关联的所需无服务器使用策略。
新增于 Databricks CLI 版本 0.273.0

database_instance.parent_instance_ref

Type: Map

父实例的引用。 仅当实例为子实例时,此实例才可用。

Key 类型 Description
branch_time String ref 数据库实例的分支时间。 对于父 ref 实例,这是创建实例的父实例的时间点。 对于子引用实例,这是创建子实例的实例的时间点。
lsn String 用户指定的 ref 数据库实例的 WAL LSN。
name String ref 数据库实例的名称。

Example

以下示例使用相应的 数据库目录定义数据库实例:

resources:
  database_instances:
    my_instance:
      name: my-instance
      capacity: CU_1
  database_catalogs:
    my_catalog:
      database_instance_name: ${resources.database_instances.my_instance.name}
      name: example_catalog
      database_name: my_database
      create_database_if_not_exists: true

有关演示如何定义数据库实例和相应数据库目录的示例捆绑包,请参阅 bundle 示例GitHub存储库。

实验

Type: Map

试验资源允许在捆绑包中定义 MLflow 试验 。 有关 MLflow 试验的信息,请参阅 使用 MLflow 试验组织训练运行。

声明式自动化捆绑包的 Python 支持实验。 参见 databricks.bundles.experiments。

experiments:
  <experiment-name>:
    <experiment-field-name>: <experiment-field-value>
Key 类型 Description
artifact_location String 存储试验项目的位置。 该位置必须包含 URI 方案,例如 dbfs: 或 s3:。 若要将项目存储在 Unity 目录卷中(建议使用 MLflow 2.15.0 或更高版本),请使用表单 dbfs:/Volumes/<catalog>/<schema>/<volume>/<path>的路径。 请参阅 从工作区创建试验。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 标识试验的易记名称。 例如 /Workspace/Users/someone@example.com/my_experiment,试验名称必须是 Databricks 工作区中的绝对路径。
permissions Sequence 试验的权限。 查看 权限。
tags Sequence 其他元数据键值对。 请参阅 标记。 若要设置试验的说明,请使用 mlflow.note.content 标记。 若要附加无服务器预算策略,请使用 mlflow.workload_creation_policy_id 标记。 请参阅 使用无服务器使用策略的属性使用情况。

Example

以下示例定义了所有用户都可以查看的试验:

resources:
  experiments:
    experiment:
      name: /Workspace/Users/someone@example.com/my_experiment
      permissions:
        - level: CAN_READ
          group_name: users
      tags:
        - key: mlflow.note.content
          value: MLflow experiment used to track runs

external_location(Unity 目录)

Type: Map

外部位置资源允许在捆绑包中定义 外部位置 (Unity 目录)。

声明式自动化捆绑包的 Python 支持外部位置。 参见 databricks.bundles.external_locations。

Note

仅当使用 直接部署引擎时,才支持使用声明性自动化捆绑包来定义外部位置。

在Databricks CLI版本0.289.0中添加

external_locations:
  <external-location-name>:
    <external-location-field-name>: <external-location-field-value>
Key 类型 Description
comment String 用户提供的外部位置的免费格式文本说明。
在Databricks CLI版本0.289.0中添加
credential_name String 必填。 用于此位置的存储凭据的名称。
在Databricks CLI版本0.289.0中添加
enable_file_events 布尔 是否对此外部位置启用文件事件。 默认为 true。 实际应用的值可能因服务器端默认值而异。 检查 effective_enable_file_events 有效状态。
在Databricks CLI版本0.289.0中添加
encryption_details Map 适用于连接到云存储的客户端的加密选项。 请参阅 external_location.encryption_details。
在Databricks CLI版本0.289.0中添加
fallback 布尔 指示是否为此外部位置启用了回退模式。 启用回退模式后,如果 Unity 目录凭据不足,则对位置的访问将回退到群集凭据。
在Databricks CLI版本0.289.0中添加
file_event_queue Map 此外部位置的文件事件队列设置。 enable_file_events如果没有false,则必须定义此键,并且必须完全具有一个记录的属性。 请参阅 external_location.file_event_queue。
在Databricks CLI版本0.289.0中添加
grants Sequence 与外部位置关联的授予。 请参阅 授予。
在Databricks CLI版本0.289.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.289.0中添加
name String 必填。 外部位置的名称。
在Databricks CLI版本0.289.0中添加
read_only 布尔 指示外部存储位置是否为只读。
在Databricks CLI版本0.289.0中添加
skip_validation 布尔 跳过与外部位置关联的存储凭据的验证。
在Databricks CLI版本0.289.0中添加
url String 必填。 外部位置的路径 URL。
在Databricks CLI版本0.289.0中添加

external_location.encryption_details

Type: Map

适用于连接到云存储的客户端的加密选项。

Key 类型 Description
sse_encryption_details Map 与 Amazon S3 通信的客户端的服务器端加密属性。

external_location.file_event_queue

Type: Map

此外部位置的文件事件队列设置。

Key 类型 Description
managed_aqs Map 托管Azure 队列存储设置。
managed_pubsub Map 托管的 Google Cloud Pub/Sub 设置。
managed_sqs Map 托管的 Amazon SQS 设置。
provided_aqs Map 用户提供的Azure 队列存储设置。
provided_pubsub Map 用户提供的 Google Cloud Pub/Sub 设置。
provided_sqs Map 用户提供的 Amazon SQS 设置。

Example

# databricks.yml
bundle:
  name: external-locations-example
  engine: direct # External locations require the direct deployment engine

resources:
  external_locations:
    my_external_location:
      name: my_external_location
      url: 's3://my-bucket/my-path'
      credential_name: my_storage_credential
      comment: 'External location created by Declarative Automation Bundles'
      grants:
        - principal: someone@example.com
          privileges:
            - CREATE_EXTERNAL_TABLE
            - READ_FILES

特色

Type: Map

功能资源允许你在捆绑包中定义特征视图。 特征视图声明了特征如何从数据源计算。 有关特征视图的信息,请参见 特征视图。

特征视图只是定义。 它什么都不算,直到 materialization_set 命名它。 关于定义特征视图及其具体化的教程,请参见 “使用声明式自动化捆绑包管理特征视图”。

声明式自动化捆绑包的 Python 支持相关功能。 详见 databricks.bundles.features。

Note

该资源需要直接部署引擎。 参见 资源兼容性。

在Databricks CLI版本1.22.0中添加

features:
  <feature-name>:
    <feature-field-name>: <feature-field-value>
Key 类型 Description
description String 特征视图的描述。 这是唯一可以在不重建特征视图的情况下更改的字段。
在Databricks CLI版本1.22.0中添加
entities Sequence 该功能所依赖的实体列。 为每个不同列组合生成特征值。 未设置为功能视图。request_source 参见 feature.entities。
在Databricks CLI版本1.22.0中添加
full_name String 必填。 特征视图的三级Unity目录名称,形式 <catalog-name>.<schema-name>.<feature-name>为 。
在Databricks CLI版本1.22.0中添加
function Map 必填。 产生特征值的计算。 参见 feature.function。
在Databricks CLI版本1.22.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.22.0中添加
lineage_context Map 背景记录在特征视图中用于谱系。 写入时接受,读时未退回。
在Databricks CLI版本1.22.0中添加
source Map 必填。 特征计算所依赖的数据。 详见 feature.source。
在Databricks CLI版本1.22.0中添加
timeseries_column Map 源列,按时间顺序排列行。 时间窗口聚合是必需的,且在 request_source. 参见 feature.timeseries_column。
在Databricks CLI版本1.22.0中添加

feature.entities

Type: Sequence

该功能所依赖的实体列。

在Databricks CLI版本1.22.0中添加

列表中的每个项目都有以下密钥:

Key 类型 Description
name String 必填。 实体列的名称。 对于 Kafka 或 Stream 源,可以用点符号标注记录键或值中的字段,例如 value.user_id 或 key.partition_key。 对于嵌套字段,具体化的表会保存叶子名称,例如 user_id 对于 value.trip_details.user_id,并且查询时该名称应使用。 冒号符号 value:user_id,如 ,支持向后兼容,但已被弃用。 改用点符号。
在Databricks CLI版本1.22.0中添加

feature.function

Type: Map

产生特征值的计算。 只设置一个函数类型。

在Databricks CLI版本1.22.0中添加

Key 类型 Description
aggregation_function Map 一个时间窗口内的聚合。 取 , approx_percentile, avgvar_popstddev_sampstddev_poplastcount_functionsumminmaxfirst与var_samp一个 ,以及 ,其中一个approx_count_distinct,sawtoothslidingrollingtumbling且 ,time_window 关于窗口的持续时间,请参见 “指定窗口、源或函数的持续时间”。
在Databricks CLI版本1.22.0中添加
column_selection Map 每个实体键的单一源列的最新值,且无聚合。 取所需 column,即源列的名称。 该 column_selection 功能仅在在线商店中实现。 参见 列选择实现。
在Databricks CLI版本1.22.0中添加
custom_udf Map (私有预览)Unity 目录用户自定义功能。 custom_udf特征无法实现。
在Databricks CLI版本1.22.0中添加

feature.source

Type: Map

特征视图的计算数据。 设置仅一个源类型,且可选 lateness。

在Databricks CLI版本1.22.0中添加

Key 类型 Description
delta_table_source Map Unity 目录中的一个 Delta 表,标识为 full_name。 可选地取 filter_condition、 transformation_sql、 dataframe_schema和 。 dataframe_schema 每当 transformation_sql 设置时,都是必需的。 在特征视图的 entitiestimeseries_column和 上声明键和时间列。
在Databricks CLI版本1.22.0中添加
feature_view_source Map (私密预览)其他特征视图,列于 feature_references。 该源的特写无法具体呈现。
在Databricks CLI版本1.22.0中添加
kafka_source Map 卡夫卡来源,由 识别 name,该来源标明了可阅读的卡夫卡配置,且可能与主题名称不同。 可选地取 filter_condition。 在特征视图自身entities的 和 timeseries_column上声明键列和时间列,记录中的字段地址,使用如 的点符号。value.user_id
在Databricks CLI版本1.22.0中添加
lateness Map 对于源行乱序,等待多久,作为 settling_delay. 不支持带 sawtooth 窗口的功能视图。 参见 “指定窗口、源或函数的持续时间”。
在Databricks CLI版本1.22.0中添加
request_source Map 请求中提供的数据在服务时间时提供,而非从存储读取,由 flat_schema 标量类型字段描述。 该源的特写无法具体呈现。
在Databricks CLI版本1.22.0中添加
stream_source Map Unity目录中注册的流,标识为 full_name。 可选地取 filter_condition。 流不是捆绑资源。 先创建并用名称引用。 参见 设置直播。
在Databricks CLI版本1.22.0中添加

feature.timeseries_column

Type: Map

源列用于按时间顺序排列行,用于时间点连接、回填和聚合。

在Databricks CLI版本1.22.0中添加

Key 类型 Description
name String 必填。 时间序列列的名称。 对于卡夫卡或Stream源,记录中的字段用点符号标注,例如 value.event_timestamp。 对于嵌套字段,具体化的表会保存叶子名称,例如 event_timestamp 对于 value.event_details.event_timestamp,并且查询时该名称应使用。 冒号符号 value:event_timestamp,如 ,支持向后兼容,但已被弃用。 改用点符号。
在Databricks CLI版本1.22.0中添加

指定窗口、源或函数的时长

Type: String

特征视图中一个字段需要时长,以秒数计时表示,后缀s604800s如七天。 这涵盖 window_duration了 、 slide_duration、 delay以及 offsettime_window在 、 以及 settling_delayfeature.source 上。 sawtooth窗口不支持 delay,带有sawtooth窗口的功能视图不支持 lateness。

更改特征视图

description 是API唯一可以更改的密钥。 更改到其他键时,功能视图会被替换。 该 bundle 删除该文件并创建新文件,并将 databricks bundle plan 动作报告为 recreate。 databricks bundle deploy 在替换或删除功能视图前请求确认,未经您的批准 --auto-approve不得继续。

一个特征视图如果实体集仍然实现,无法被替换,因为在实体化特征时其删除会被拒绝。 要更改它,先从集合中移除其实体化特征并部署,然后更改特征视图,重新添加实体化特征,再次部署。 重新加入它们会替换集合,因此集合中每个物质化特征都会被重新计算。

Example

以下示例定义了一个功能视图,该视图统计每个用户在过去七天内的交易量,每天重新计算。

YAML
resources:
  features:
    transaction_count:
      full_name: ${var.catalog}.${var.schema}.transaction_count_7d
      description: Transactions per user over a trailing seven days
      source:
        delta_table_source:
          full_name: ${var.source_table}
      function:
        aggregation_function:
          count_function:
            input: transaction_id
          time_window:
            sliding:
              window_duration: 604800s
              slide_duration: 86400s
      entities:
        - name: user_id
      timeseries_column:
        name: transaction_time
Python
def load_resources(bundle: Bundle) -> Resources:
    resources = Resources()

    resources.add_feature(
        'transaction_count',
        Feature(
            full_name='${var.catalog}.${var.schema}.transaction_count_7d',
            description='Transactions per user over a trailing seven days',
            source=DataSource(
                delta_table_source=DeltaTableSource(full_name='${var.source_table}')
            ),
            function=Function(
                aggregation_function=AggregationFunction(
                    count_function=CountFunction(input='transaction_id'),
                    time_window=TimeWindow(
                        sliding=SlidingWindow(window_duration='604800s', slide_duration='86400s')
                    ),
                )
            ),
            entities=[EntityColumn(name='user_id')],
            timeseries_column=TimeseriesColumn(name='transaction_time'),
        ),
    )

    return resources

feature_spec

重要

此功能以个人预览版提供。 若要试用,请联系 Azure Databricks 联系人。

Type: Map

feature_spec资源允许您在捆绑中定义 FeatureSpecs。 A FeatureSpec 是一个 Unity 目录函数,列出了要通过特征服务端点或用于模型训练的特征。 有关 s 的信息 FeatureSpec,请参见 “服务功能表”。

要提供 FeatureSpec,声明一个 model_serving_endpoint ,其 served_entities 条目设 entity_name 为 spec name。 如需声明两者的教程,请参阅 《使用声明式自动化捆绑为功能视图提供服务》。

Python 中声明式自动化捆绑包支持 FeatureSpecs。 请看 databricks.bundles.feature_specs。

Note

该资源需要直接部署引擎。 参见 资源兼容性。

在 Databricks CLI 1.26.0 版本中新增

feature_specs:
  <feature_spec-name>:
    <feature_spec-field-name>: <feature_spec-field-value>
Key 类型 Description
exclude_columns Sequence 要从中省略 FeatureSpec的列的输出名称。 秩序并不重要。
在 Databricks CLI 1.26.0 版本中新增
extra_pip_requirements Map 在上菜容器里安装额外的 pip 要求。 参见 feature_spec.extra_pip_requirements。
在 Databricks CLI 1.26.0 版本中新增
features Sequence 必填。 他们 FeatureSpec 所提供的各种功能。 参见 feature_spec.features。
在 Databricks CLI 1.26.0 版本中新增
grants Sequence 与 FeatureSpec相关 的资助。 A FeatureSpec 是一个 Unity 目录函数,因此权限是函数权限,例如 EXECUTE。 请参阅 授予。
在 Databricks CLI 1.26.0 版本中新增
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在 Databricks CLI 1.26.0 版本中新增
name String 必填。 三级 Unity 目录名称 FeatureSpec,形式为 <catalog-name>.<schema-name>.<feature-spec-name>。
在 Databricks CLI 1.26.0 版本中新增

feature_spec.特点

Type: Sequence

他们 FeatureSpec 所提供的各种功能。 每个条目恰好设置以下一个键。

Key 类型 Description
declarative_feature Map 要服务的功能视图。 其唯一键 feature,为必填键,并承载特征视图的三级名称,例如 ${resources.features.<feature-name>.full_name}。
在 Databricks CLI 1.26.0 版本中新增
feature_function Map 一个 Python 用户自定义函数(UDF)从其他功能中计算出来的特征。 参见 feature_spec.features.feature_function。
在 Databricks CLI 1.26.0 版本中新增
feature_lookup Map 从特征表中查找特征。 参见 feature_spec.features.feature_lookup。
在 Databricks CLI 1.26.0 版本中新增

feature_spec.features.feature_lookup

Type: Map

从特征表中查找特征。

Key 类型 Description
default_values Sequence 特征的默认值。 每个项目都有一个必填 feature 键,如果重命名特征,则以输出名称命名该特征,否则则以特征表中的名字命名该特征,并配有一个 default_value 键。 秩序并不重要。
在 Databricks CLI 1.26.0 版本中新增
feature_names Sequence 要查找的特征名称。 如果为空,则查找表中的所有特征。
在 Databricks CLI 1.26.0 版本中新增
lookback_window String 时间点查找的回溯窗口,以秒为单位的持续时间,例如 86400s。 需要 timestamp_lookup_keys。
在 Databricks CLI 1.26.0 版本中新增
lookup_keys Sequence 必填。 与特征表连接的密钥。
在 Databricks CLI 1.26.0 版本中新增
rename_outputs Sequence 以输出名称替换特征表中的名称。 每个物品都有一个必需 feature 的密钥和一个必需 output 密钥。 秩序并不重要。
在 Databricks CLI 1.26.0 版本中新增
table String 必填。 特征表的三级名称。
在 Databricks CLI 1.26.0 版本中新增
timestamp_lookup_keys Sequence 用于时间点查询的密钥。
在 Databricks CLI 1.26.0 版本中新增

feature_spec.features.feature_function

Type: Map

Python UDF 从其他特征中计算出的一种特征。

Key 类型 Description
input_bindings Sequence UDF 参数与特征的绑定。 每个项目都有一个必填 parameter 键,用于命名 UDF 参数,以及一个必填 bound_feature 键,用于命名绑定到该参数的特征。 秩序并不重要。
在 Databricks CLI 1.26.0 版本中新增
output String UDF 计算的特征的输出名称。
在 Databricks CLI 1.26.0 版本中新增
udf String 必填。 Python UDF 的三级名称。
在 Databricks CLI 1.26.0 版本中新增

feature_spec.extra_pip_requirements

Type: Map

除了默认设置以及功能中解决的设置外,还需要在服务容器中安装额外的 PIP 要求。

Key 类型 Description
requirements Sequence 必填。 每个项目是 PEP 508 包指定符,或是 Unity 目录卷/Volumes/...中轮子文件的路径()。 秩序并不重要。
在 Databricks CLI 1.26.0 版本中新增

特征规范必须满足的规则

除非满足以下所有条件,否则创建请求会被拒绝:

  • features 至少有一个元素,每个元素恰好设置一个 declarative_feature、 feature_lookup或 feature_function。
  • FeatureSpec A(在 中features)declarative_feature没有 feature_lookup 或 feature_function 元素,且不设 exclude_columns。
  • 条目所命名的每个特征视图 declarative_feature 都有一个在线实体化特征。 否则,创建失败。No online materialized feature found for features: <names>
  • 用于实现每个特征视图的实体化集是在 FeatureSpec。 ${resources.features...}引用只在特征视图之后排序FeatureSpec,因此当集合属于同一捆绑包时,为其添加lifecycle.depends_on条目。 然后,该组合在集合之后创建该集合 FeatureSpec ,并在集合集合之前删除它。 请参阅 生命周期。
  • 在 、 default_values中没有两个项目rename_outputs,或input_bindings名称相同的特征或参数,没有rename_outputs项目保留特征自身的名称,且没有列出现两次。exclude_columns
  • extra_pip_requirements.requirements,当设置为时,至少包含一个项目。

当特征视图以批处理模式实现时,其在线表仅在实体化集首次运行后才存在。 一个功能服务端点,在 FeatureSpec 该运行失败前已部署 和 。 在第一次运行后再次运行 databricks bundle deploy ,部署将重新创建失败的端点。

更改功能规范

对任意键的更改会替换 FeatureSpec。 该 bundle 删除该文件并创建新文件,并将 databricks bundle plan 动作报告为 recreate。 databricks bundle deploy 先请求确认,并在 上 FeatureSpec 承认该组合未宣告丢失。 重新排序 exclude_columns、 extra_pip_requirements.requirements或条目中的 rename_outputs、 default_values或 input_bindings 不是更改。 重新排序 features,或者 feature_lookup 条目中的 feature_names, lookup_keys或者 timestamp_lookup_keys,是。

正在运行的功能服务端点在被替换时 FeatureSpec 仍会继续提供其构建时所包含的功能,但保留其名称。 要更改端点所服务的内容,请赋予 FeatureSpec 新的 name. 在同一部署中更新的端点,其 entity_name 引用的 FeatureSpec' name s。 有关工作示例,请参见 重命名特征规格。

删除未被阻止名称 FeatureSpec 的功能视图,导致该 FeatureSpec 视图过时。

Examples

以下示例定义了服务两个功能视图的 和FeatureSpec一个服务于 的功能服务端点。FeatureSpec 依赖 FeatureSpecevent_features 于实体化集 ,该集合 serving_online将功能视图 events_90mamount_sum_90m和 都实体化到在线商店。

YAML
resources:
  feature_specs:
    event_features:
      name: ${var.catalog}.${var.schema}.event_features
      features:
        - declarative_feature:
            feature: ${resources.features.events_90m.full_name}
        - declarative_feature:
            feature: ${resources.features.amount_sum_90m.full_name}
      lifecycle:
        depends_on:
          - resource: materialization_sets.serving_online

  model_serving_endpoints:
    event_endpoint:
      name: event-features
      config:
        served_entities:
          - entity_name: ${resources.feature_specs.event_features.name}
            workload_size: Small
            scale_to_zero_enabled: true
Python
def load_resources(bundle: Bundle) -> Resources:
    resources = Resources()

    resources.add_feature_spec(
        'event_features',
        FeatureSpec(
            name='${var.catalog}.${var.schema}.event_features',
            features=[
                Features(
                    declarative_feature=DeclarativeFeature(
                        feature='${resources.features.events_90m.full_name}'
                    )
                ),
                Features(
                    declarative_feature=DeclarativeFeature(
                        feature='${resources.features.amount_sum_90m.full_name}'
                    )
                ),
            ],
            lifecycle=Lifecycle(
                depends_on=[DependsOn(resource='materialization_sets.serving_online')]
            ),
        ),
    )

    resources.add_model_serving_endpoint(
        'event_endpoint',
        ModelServingEndpoint(
            name='event-features',
            config=EndpointCoreConfigInput(
                served_entities=[
                    ServedEntityInput(
                        entity_name='${resources.feature_specs.event_features.name}',
                        workload_size='Small',
                        scale_to_zero_enabled=True,
                    )
                ]
            ),
        ),
    )

    return resources

下面的示例定义了 ,FeatureSpec它从 特征表中查找两个特征,并使用 Python UDF 计算第三个特征。 功能表和 UDF 不是捆绑包资源,因此在部署捆绑包之前,请将它们创建在捆绑包之外。 参见 创建 FeatureSpec。

YAML
resources:
  feature_specs:
    user_features_spec:
      name: ${var.catalog}.${var.schema}.user_features_spec
      features:
        - feature_lookup:
            table: ${var.catalog}.${var.schema}.user_features
            lookup_keys: [user_id]
            feature_names: [age, country]
        - feature_function:
            udf: ${var.catalog}.${var.schema}.age_score
            input_bindings:
              - parameter: age
                bound_feature: age
            output: age_score
Python
def load_resources(bundle: Bundle) -> Resources:
    resources = Resources()

    resources.add_feature_spec(
        'user_features_spec',
        FeatureSpec(
            name='${var.catalog}.${var.schema}.user_features_spec',
            features=[
                Features(
                    feature_lookup=FeatureLookup(
                        table='${var.catalog}.${var.schema}.user_features',
                        lookup_keys=['user_id'],
                        feature_names=['age', 'country'],
                    )
                ),
                Features(
                    feature_function=FeatureFunction(
                        udf='${var.catalog}.${var.schema}.age_score',
                        input_bindings=[
                            FeatureFunctionInputBinding(parameter='age', bound_feature='age')
                        ],
                        output='age_score',
                    )
                ),
            ],
        ),
    )

    return resources

genie_space

Type: Map

使用 Genie 代理资源可以在捆绑包中定义 Genie 代理 。 有关 Genie 代理的详细信息,请参阅 Genie 代理。

声明式自动化包的 Python 支持Genie空间。 请看 databricks.bundles.genie_spaces。

Note

仅当使用 直接部署引擎时,才支持使用声明性自动化捆绑包来定义 Genie 代理。

在Databricks CLI版本1.3.0中添加

genie_spaces:
  <genie_space-name>:
    <genie_space-field-name>: <genie_space-field-value>
Key 类型 Description
description String Genie 代理说明。
在Databricks CLI版本1.3.0中添加
file_path String 将使用的本地文件(例如, sales_analytics.geniespace.json)的路径,而不是 serialized_space 条目。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.3.0中添加
parent_path String 将注册 Genie 代理的父文件夹路径。
在Databricks CLI版本1.3.0中添加
permissions Sequence Genie 代理权限。 查看 权限。
在Databricks CLI版本1.3.0中添加
serialized_space String 必填。 以序列化字符串形式表示的 Genie 代理的内容。 此字段提供表示空间布局和组件的 JSON 字符串的结构。 如果 file_path 指定为,则优先于 serialized_space。
在Databricks CLI版本1.3.0中添加
title String Genie 代理的可选游戏替代。
在Databricks CLI版本1.3.0中添加
warehouse_id String 必填。 要与新空间关联的 SQL 仓库的 ID。
在Databricks CLI版本1.3.0中添加

Examples

以下示例定义 Genie 代理资源:

# databricks.yml
bundle:
  name: nyc-taxi-genie
  engine: direct # genie_spaces require the direct deployment engine

resources:
  genie_spaces:
    nyc_taxi_genie:
      title: 'NYC Taxi Trip Analysis'
      description: 'Ask questions about NYC taxi trip data in natural language'
      warehouse_id: <warehouse-id>
      file_path: ./nyc_taxi_genie.geniespace.json
      permissions:
        - level: CAN_RUN
          group_name: users

相应的 nyc_taxi_genie.geniespace.json 文件保存空间的序列化定义,包括其数据源、说明和示例问题。 也可以改为在 YAML 中 serialized_space 指定它。

// nyc_taxi_genie.geniespace.json
{
  "version": 2,
  "config": {
    "sample_questions": [
      {
        "id": "11111111111111111111111111111111",
        "question": ["What is the average fare per trip?"]
      }
    ]
  },
  "data_sources": {
    "tables": [
      {
        "identifier": "samples.nyctaxi.trips",
        "column_configs": [
          { "column_name": "fare_amount" },
          { "column_name": "pickup_zip" },
          { "column_name": "tpep_pickup_datetime" },
          { "column_name": "trip_distance" }
        ]
      }
    ]
  },
  "instructions": {
    "text_instructions": [
      {
        "id": "22222222222222222222222222222222",
        "content": ["Fare amounts are in USD. When asked about revenue, use SUM(fare_amount)."]
      }
    ]
  }
}

instance_pool

Type: Map

instance_pool资源允许你在捆绑包中定义 实例池 。 实例池保留一组闲置、现成可用的云实例,使连接到池的集群能够更快地启动和扩展。 有关实例池的信息,请参见 “连接池”。

声明式自动化捆绑包的 Python 支持实例池。 参见 databricks.bundles.instance_pools。

Note

只有在使用 直接部署引擎的情况下,才支持使用声明式自动化捆绑来定义实例池。

在Databricks CLI版本1.9.0中添加

instance_pools:
  <instance_pool-name>:
    <instance_pool-field-name>: <instance_pool-field-value>
Key 类型 Description
aws_attributes Map 与运行在亚马逊网络服务上的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。 参见 instance_pool.aws_attributes。
在Databricks CLI版本1.9.0中添加
azure_attributes Map 与Azure上运行的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。 参见 instance_pool.azure_attributes。
在Databricks CLI版本1.9.0中添加
custom_tags Map 池资源的额外标签。 Databricks 除了 ,还会用这些标签 default_tags标记所有池资源(例如 AWS 实例和 EBS 卷)。 Databricks 最多允许 45 个自定义标签。
在Databricks CLI版本1.9.0中添加
disk_spec Map 磁盘的规格要求安装在所有火花容器上。 参见 instance_pool.disk_spec。
在Databricks CLI版本1.9.0中添加
enable_elastic_disk 布尔 本地存储自动扩展:启用后,该池中的实例在 Spark 工作者磁盘空间不足时动态获得额外磁盘空间。 在AWS中,此功能需要特定的AWS权限才能正常运行。
在Databricks CLI版本1.9.0中添加
gcp_attributes Map 与运行在谷歌云平台上的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。 参见 instance_pool.gcp_attributes。
在Databricks CLI版本1.9.0中添加
idle_instance_autotermination_minutes Integer 如果 min_idle_instances 满足需求,几分钟内自动终止池缓存中的额外实例,时间为数分钟。 如果未设置,额外的池实例在默认超时后会自动终止。 如果指定,阈值必须介于 0 和 10000 分钟之间。 将该值 0 设置为,如果最小缓存大小仍可保持,则立即从缓存中移除空闲实例。
在Databricks CLI版本1.9.0中添加
instance_pool_name String 必填。 池名称。 池名必须是唯一的,长度必须在1到100字符之间。
在Databricks CLI版本1.9.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.9.0中添加
max_capacity Integer 池中应保留的最大未解决实例数,包括集群和闲置实例。 需要进一步实例配置的集群在升级请求时会失败。
在Databricks CLI版本1.9.0中添加
min_idle_instances Integer 实例池中最少需要保留的闲置实例数量。
在Databricks CLI版本1.9.0中添加
node_type_flexibility Map 池的节点类型配置灵活。 参见 instance_pool.node_type_flexibility。
在Databricks CLI版本1.9.0中添加
node_type_id String 必填。 该字段通过一个单一值编码使用该池的集群中每个 Spark 节点可用的资源。 例如,可以针对内存或计算密集型工作负载对 Spark 节点进行预配和优化。 可以使用 列表节点类型 API 检索可用节点类型的列表。
在Databricks CLI版本1.9.0中添加
permissions Sequence 实例池权限。 允许的级别为 CAN_MANAGE 和 CAN_ATTACH_TO。 查看 权限。
在Databricks CLI版本1.9.0中添加
preloaded_docker_images Sequence 预加载在池实例上的自定义Docker镜像。 参见 instance_pool.preloaded_docker_images。
在Databricks CLI版本1.9.0中添加
preloaded_spark_versions Sequence 一个最多包含一个预加载的 Spark 镜像版本的列表。 池支持集群启动时预加载的 Spark 版本会更快启动。 可以使用 列表可用的 Spark 版本 API 检索可用的 Spark 版本列表。
在Databricks CLI版本1.9.0中添加
remote_disk_throughput Integer 远程磁盘的可配置吞吐量,单位为MB每秒。 目前仅支持 GCP HYPERDISK_BALANCED 类型。
在Databricks CLI版本1.9.0中添加
total_initial_remote_disk_size Integer 远程磁盘的初始总卷大小(GB)。 目前仅支持 GCP HYPERDISK_BALANCED 类型。
在Databricks CLI版本1.9.0中添加

instance_pool.aws_attributes

Type: Map

与运行在亚马逊网络服务上的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
availability String 即时节点使用的可用性类型。 有效值为 SPOT 和 ON_DEMAND。
在Databricks CLI版本1.9.0中添加
instance_profile_arn String (测试版)所有属于实例池的 AWS 实例都拥有这个实例配置文件。 如果省略,实例最初会以工作区的默认实例配置文件启动。 如果定义了,使用该池的集群继承了实例配置文件,且在创建或更新集群时不得指定自己的实例配置文件。 如果池没有指定实例配置文件,使用该池的集群可以指定任何实例配置文件。 实例配置文件必须由账户管理员事先添加到Databricks环境中。 此功能可能仅对特定客户套餐开放。
在Databricks CLI版本1.9.0中添加
spot_bid_price_percent Integer 计算AWS现货实例的竞价价格,按相应实例按需价格的百分比计算。 例如,如果该字段设置为 , 50 且池需要一个新的 r3.xlarge 现货实例,那么出价价格是按需 r3.xlarge 实例价格的一半。 如果未指定,默认值为 100。 该域不得超过 10000。
在Databricks CLI版本1.9.0中添加
zone_id String 例如,池所在的可用性区域/数据中心 us-west-2a标识符。 提供的可用区域必须与Databricks部署区域相同。 这是一个可选字段,如果未指定,则使用默认区域。 可用区域列表及默认值可通过 列表区域API查询。
在Databricks CLI版本1.9.0中添加

instance_pool.azure_attributes

Type: Map

与Azure上运行的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
availability String 即时节点使用的可用性类型。 有效值为 SPOT_AZURE 和 ON_DEMAND_AZURE。
在Databricks CLI版本1.9.0中添加
capacity_reservation_group String 用于启动虚拟机的Azure容量预留组资源ID。 指定后,虚拟机会根据提供的容量预留启动。 省略该字段会清除池中任何已配置的容量预留组。
只有当工作区使用注入的VNet(客户定义的VNet,未由Databricks管理)时,才能指定容量预留。 databricks-login-prod企业应用必须获得以下四项权限:
  • Microsoft.Compute/capacityReservationGroups/read
  • Microsoft.Compute/capacityReservationGroups/deploy/action
  • Microsoft.Compute/capacityReservationGroups/capacityReservations/read
  • Microsoft.Compute/capacityReservationGroups/capacityReservations/deploy/action

使用 /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{capacityReservationGroupName} 格式。
在Databricks CLI版本1.9.0中添加
spot_bid_max_price 编号 Azure 现货实例的最高价格,以美元(USD)计。 例如,该价值 2 设定了每小时2.00美元。 把最高价格设为 -1 不会因为价格而驱逐虚拟机。 虚拟机的价格是当前现货价格或标准虚拟机价格,以较低者为准,只要有容量和配额。
在Databricks CLI版本1.9.0中添加

instance_pool.disk_spec

Type: Map

磁盘的规格要求安装在所有火花容器上。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
disk_count Integer 每个实例启动的磁盘数量。 此功能仅在支持的节点类型下启用,你可以选择该节点类型支持的磁盘数量上限。 对于没有操作系统磁盘的节点类型,至少必须指定一个磁盘,否则集群创建将失败。
如果连接了磁盘,Databricks 会配置 Spark 仅使用磁盘作为临时存储,因为异构的临时设备会导致磁盘利用效率低下。 如果没有连接磁盘,Databricks 会配置 Spark 使用实例存储磁盘。 如果指定了磁盘,则Spark配置 spark.local.dir 被覆盖。
磁盘挂载于 /ebs0,/ebs1AWS 的 /remote_volume0/remote_volume1,依此类推,对于 Azure 的,依此类推。
在Databricks CLI版本1.9.0中添加
disk_iops Integer 每个附加磁盘需要配置的IOPS数量。
在Databricks CLI版本1.9.0中添加
disk_size Integer 每个磁盘的大小(以 GiB)为单位,为每个实例启动。 值必须落在特定实例类型的支持范围内。 对于AWS,通用SSD容量为100–4096 GiB,吞吐量优化的硬盘为500–4096 GiB。 对于 Azure,高级 LRS(SSD)为 1–1023 GiB,标准 LRS(HDD)为 1–1023 GiB。
在Databricks CLI版本1.9.0中添加
disk_throughput Integer 每个附加磁盘的磁盘吞吐量,单位为MB每秒。
在Databricks CLI版本1.9.0中添加
disk_type Map 随池实例启动的磁盘类型。 设( azure_disk_volume_type 有效值为 PREMIUM_LRS 和 STANDARD_LRS)或 ebs_volume_type (有效值为 GENERAL_PURPOSE_SSDTHROUGHPUT_OPTIMIZED_HDD和 )。
在Databricks CLI版本1.9.0中添加

instance_pool.gcp_attributes

Type: Map

与运行在谷歌云平台上的实例池相关的属性。 如果创建池时未指定,则使用一组默认值。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
gcp_availability String 确定实例池是否包含抢占式虚拟机、按需虚拟机,还是在前者不可用时可退回点播虚拟机的抢占式虚拟机。 有效值为:PREEMPTIBLE_GCP、ON_DEMAND_GCP 和 PREEMPTIBLE_WITH_FALLBACK_GCP。
在Databricks CLI版本1.9.0中添加
local_ssd_count Integer 如果提供,实例池中的每个节点都连接了相同数量的本地 SSD。 每个本地SSD容量为375GB。 关于每种实例类型支持的本地SSD数量,请参见 GCP文档。
在Databricks CLI版本1.9.0中添加
zone_id String 例如,池所在的可用性区域/数据中心 us-west1-a标识符。 所提供的可用区域必须与Databricks工作区处于同一区域。 这是一个可选字段,如果未指定,则使用默认区域。 将该字段 HA 设置为高可用性,将节点分布在Databricks部署区域的不同可用区域,或是该机器类型和区域的 可用区域 之一。 如果空了,Databricks 会选择一个可用区。
在Databricks CLI版本1.9.0中添加

instance_pool.node_type_flexibility

Type: Map

池的节点类型配置灵活。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
alternate_node_type_ids Sequence 当主节点类型不可用时用作回退的节点类型 ID 的列表。
在Databricks CLI版本1.9.0中添加
aws_context_id String EC2车队的AWS上下文ID。 当设置为非空时,该值会传递给AWS CreateFleet API,以创建EC2舰队。
在Databricks CLI版本1.16.0中添加

instance_pool.preloaded_docker_images

Type: Sequence

预加载在池实例上的自定义Docker镜像。

在Databricks CLI版本1.9.0中添加

Key 类型 Description
basic_auth Map Docker 仓库的基本认证。 设置 username 和 password。
在Databricks CLI版本1.9.0中添加
url String Docker 镜像的网址。
在Databricks CLI版本1.9.0中添加

Example

以下示例定义了一个实例池及其集群:

resources:
  instance_pools:
    my_pool:
      instance_pool_name: my-pool
      node_type_id: i3.xlarge
      min_idle_instances: 2
      max_capacity: 10
      idle_instance_autotermination_minutes: 15
      preloaded_spark_versions:
        - '15.4.x-scala2.12'

  clusters:
    my_cluster:
      cluster_name: my-cluster
      instance_pool_id: ${resources.instance_pools.my_pool.id}
      spark_version: '15.4.x-scala2.12'
      num_workers: 2

工作

Type: Map

作业资源允许你在捆绑包中定义 作业及其相应的任务 。

声明式自动化捆绑包的 Python 支持作业。 请参阅 databricks.bundles.jobs。

有关工作的更多信息,请参阅 Lakeflow 工作。 有关使用声明性自动化捆绑包模板创建作业的教程,请参阅 使用声明性自动化捆绑包开发作业。

jobs:
  <job-name>:
    <job-field-name>: <job-field-value>
Key 类型 Description
budget_policy_id String 要用于此作业的用户指定预算策略的 ID。 如果未指定,则创建或修改作业时,可以应用默认预算策略。 请参阅 effective_budget_policy_id 了解此工作负载使用的预算策略。
在Databricks CLI版本0.231.0中添加
continuous Map 此作业的可选连续属性。 连续属性将确保始终有一个运行在执行。 schedule 和 continuous 中只能使用一个。 由连续作业启动的管道也会连续运行,无论它们自身的管道模式设置如何。 请参阅 continuous。
deployment Map 由外部源管理的作业的部署信息。 请参阅 部署。
description String 作业的可选说明。 UTF-8 编码的最大长度为 27700 个字符。
email_notifications Map 一组可选的电子邮件地址,在此作业的运行开始或完成时,以及在删除此作业时,这些电子邮件地址将会收到通知。 请参阅 email_notifications。
environment_variables Sequence (测试版)任务可以通过键引用的命名环境变量条目。 每个条目 spec 都包含内联变量和可选 .env 文件。 每个作业最多可指定10个条目,任务最多只能引用一个条目。 参见 environment_variables。
在Databricks CLI版本1.20.0中添加的
environments Sequence 此作业的无服务器任务可以引用的任务执行环境规范列表。 需要存在环境以支持无服务器任务。 对于无服务器笔记本任务,可以在笔记本环境面板中访问环境。 对于其他无服务器任务,需要使用任务设置中的environment_key指定任务环境。 请参阅 environments。
format String Deprecated. 作业的格式。
git_source Map 远程 Git 存储库的可选规范,其中包含任务使用的源代码。 请参阅 job.git_source。
重要信息:git_source对于捆绑包,不建议将字段和任务source字段设置为 ,GIT因为本地相对路径可能不指向 Git 仓库中的相同内容,而捆绑包期望部署的作业内容与其部署的本地副本相同。
相反,会在本地克隆存储库并在此存储库中设置捆绑包项目,以便任务源是工作区。
health Map 可为此作业定义的一组可选运行状况规则。 查看 健康。
job_clusters Sequence 此作业的任务可以共享和重复使用的作业群集规范列表。 请参阅 job_clusters。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
max_concurrent_runs Integer 作业的最大允许并发运行数,可选。 如果希望能够以并发方式执行同一作业的多个运行,请设置此值。
name String 可选的作业名称。 UTF-8 编码的最大长度为 4096 字节。
notification_settings Map 向此作业的每个 email_notifications 和 webhook_notifications 发送通知时使用的可选通知设置。 请参阅 notification_settings。
parameters Sequence 作业级参数定义。 请参阅 job.parameters。
performance_target String 定义在无服务器上运行的执行的性能或成本效益。
在Databricks CLI版本0.241.0中添加
permissions Sequence 作业的权限。 查看 权限。
queue Map 作业的队列设置。 请参阅 queue。
run_as Map 工作所代表的身份。 该字段表示该作业的 run_as 显式配置。 如果未指定,作业将作为创建作业的用户运行。 精确指定其中 user_name一个 、 service_principal_name或 group_name。 如果指定多个,则会抛出错误。 请参阅 将“运行身份”设置为组。
schedule Map 此作业的可选定期计划。 默认行为是,只有通过在作业 UI 中单击“立即运行”或向该作业发送 API 请求 runNow来触发时,作业才会运行。 请参阅 计划。
tags Map 与作业关联的标记映射。 这些内容作为作业群集的群集标记转发到群集,并且受到与群集标记相同的限制。 最多可以向作业添加 25 个标记。
tasks Sequence 此作业要执行的任务规范列表。 请参阅 在声明性自动化捆绑包中向作业添加任务。
在Databricks CLI版本0.237.0中添加
timeout_seconds Integer 可选的超时设置,应用于此作业的每个运行。 值 0 意味着无超时。
trigger Map 满足某些条件时触发运行的配置。 请参阅 触发器。
triggers Sequence (测试版)一份与此任务相关的触发点列表。 当任何激活触发值被评估为真时,运行开始。 不能与遗留schedule的 、 或triggercontinuous字段在同一请求中设置。 被“多重触发器”功能预览限制。 参见 job.triggers。
在Databricks CLI版本1.13.0中添加
usage_policy_id String 用于此作业的无服务器使用策略的 ID。
新增于 Databricks CLI 版本 0.273.0
webhook_notifications Map 此作业的运行开始或完成时要通知的系统通知 ID 的集合。 请参阅 webhook_notifications。

工作。连续

Type: Map

连续作业执行的配置。

Key 类型 Description
maintenance_window Map 定义了该工作平台发起维护的时间。 如未指定,维护可随时进行。
在Databricks CLI版本1.16.0中添加
pause_status String 是否暂停连续作业。 有效值: PAUSED, UNPAUSED。
task_retry_mode String 说明持续作业如何应用任务级别重试。 有效值为 NEVER 和 ON_FAILURE。 默认为 NEVER。

工作.部署

Type: Map

由外部源管理的作业的部署信息。

Key 类型 Description
kind String 部署类型。 例如,BUNDLE。
metadata_file_path String 用于部署的元数据文件路径

job.email_notifications

Type: Map

作业运行的电子邮件通知设置。

Key 类型 Description
on_start Sequence 运行启动时要通知的电子邮件地址列表。
on_success Sequence 运行成功时要通知的电子邮件地址列表。
on_failure Sequence 运行失败时要通知的电子邮件地址列表。
on_duration_warning_threshold_exceeded Sequence 当运行持续时间超过警告阈值时通知的电子邮件地址列表。
no_alert_for_skipped_runs 布尔 是否选择跳过发送运行被跳过时的警报。
on_streaming_backlog_exceeded Sequence 任何流超过任何流积压工作阈值时要通知的电子邮件地址列表。 可以使用以下指标在health字段中设置流式积压工作阈值:STREAMING_BACKLOG_BYTES、STREAMING_BACKLOG_RECORDS或STREAMING_BACKLOG_SECONDSSTREAMING_BACKLOG_FILES。 警报基于这些指标的 10 分钟平均值。 如果问题仍然存在,则每 30 分钟重新发送一次通知。
on_maintenance_start Sequence 一个用于在平台启动维护开始时通知的电子邮件地址列表,用于持续作业。
在Databricks CLI版本1.20.0中添加的
on_maintenance_complete Sequence 一份用于在平台启动维护完成时通知的电子邮件地址列表,用于持续作业。
在Databricks CLI版本1.20.0中添加的

job.environment_variables

Type: Sequence

(测试版)任务可以通过键引用的 environment_variables_key命名环境变量条目。 每个作业最多可指定10个条目,任务最多只能引用一个条目。

在Databricks CLI版本1.20.0中添加的

列表中的每一项都是一个JobEnvironmentVariables:

Key 类型 Description
environment_variables_key String 必填。 本条目的标识符。 必须在工作 environment_variables中独一无二。 任务从任务 environment_variables_key中引用。
在Databricks CLI版本1.20.0中添加的
spec Map 环境变量规范。
在Databricks CLI版本1.20.0中添加的

工作。环境

Type: Sequence

任务执行环境规范的列表,供作业中的无服务器任务引用。

列表中的每一项都是一个JobEnvironment:

Key 类型 Description
environment_key String 环境的关键。 它必须在作业中是唯一的。
spec Map 表示无服务器环境的实体。 请参阅 job.environments.spec。

job.environments.spec

Type: Map

表示无服务器环境的实体。

Key 类型 Description
client String Deprecated. 客户端版本。
dependencies Sequence 此环境中的 pip 版本支持的 pip 依赖项列表。
environment_version String 必填。 环境使用的环境版本。 每个版本都附带特定的Python版本和一组Python包。 版本是一个字符串,由整数组成。

job.git_source

Type: Map

作业源代码的 Git 存储库配置。

Key 类型 Description
git_branch String 要签出和使用此作业的分支的名称。 此字段不能与 git_tag 或 git_commit 同时指定。
git_commit String 要签出和使用此作业的提交。 此字段不能与 git_branch 或 git_tag 同时指定。
git_provider String 用于托管 Git 存储库的服务的唯一标识符。 该值不区分大小写。 有效值为 gitHub:、bitbucketCloud、、gitLab、azureDevOpsServicesgitHubEnterprise、bitbucketServer. gitLabEnterpriseEdition
git_snapshot Map 运行作业时远程存储库的只读状态。 此字段仅在作业执行时包含。 请参阅 git_snapshot。
git_tag String 要签出和使用此作业的标记的名称。 此字段不能与 git_branch 或 git_commit 同时指定。
git_url String 要由此作业克隆的存储库的 URL。
sparse_checkout Map Git 存储库的稀疏签出配置。 请参阅 job.git_source.sparse_checkout。
在Databricks CLI版本0.290.0中添加

job.git_source.sparse_checkout

Type: Map

Git 存储库的稀疏签出配置。

在Databricks CLI版本0.290.0中添加

Key 类型 Description
patterns Sequence 用于稀疏结帐的模式列表。
在Databricks CLI版本0.290.0中添加

job.git_source.git_snapshot

Type: Map

只读提交信息快照。

Key 类型 Description
used_commit String 用于执行运行的提交。 如果 git_branch 已指定,则指向运行时分支的 HEAD。如果 git_tag 已指定,则指向提交标记所指向的提交。

工作。健康

Type: Map

健康监控配置用于作业。

Key 类型 Description
rules Sequence 作业健康规则列表。 每个规则都包含一个 metric 和 op (运算符) 和 value。 请参阅 job.health.rules。

工作.健康.规则

Type: Sequence

作业健康规则列表。

列表中的每一项都是一个JobHealthRule:

Key 类型 Description
metric String 指定正在针对特定健康规则进行评估的健康指标。
  • RUN_DURATION_SECONDS:每次跑步的预期总时间(秒数)。
  • STREAMING_BACKLOG_BYTES:所有流等待消耗的最大数据字节估计。
  • STREAMING_BACKLOG_RECORDS:所有流最大偏移滞后的估计值。
  • STREAMING_BACKLOG_SECONDS:所有流的最大消费者延迟估计值。
  • STREAMING_BACKLOG_FILES:所有流中最大未处理文件数量的估计。
op String 指定用于将运行状况指标值与指定阈值进行比较的运算符。
value Integer 指定运行状况指标应遵循的阈值以满足运行状况规则。

job.job_clusters

Type: Sequence

此作业的任务可以共享和重复使用的作业群集规范列表。 无法在共享作业群集中声明库。 必须在任务设置中声明依赖库。

列表中的每一项都是一个JobCluster:

Key 类型 Description
job_cluster_key String 作业群集的唯一名称。 此字段是必需的,并且必须在作业中是唯一的。 JobTaskSettings 可以参考该字段来决定任务执行时应启动哪个集群。
new_cluster Map 如果new_cluster,则说明为每个任务创建的群集。 请参阅 群集。

job.notification_settings

Type: Map

适用于作业中所有通知的通知设置。

Key 类型 Description
no_alert_for_skipped_runs 布尔 是否选择跳过发送运行被跳过时的警报。
no_alert_for_canceled_runs 布尔 是否跳过发送已取消运行的警报。

job.parameters(工作参数)

Type: Sequence

作业参数定义列表。

列表中的每一项都是一个JobParameter:

Key 类型 Description
default String 必填。 参数的默认值,例如“users”。
name String 必填。 定义的参数的名称,例如“table”。 有效值仅包含字母数字字符、_和 -.。

job.queue

Type: Map

作业的队列设置。

Key 类型 Description
enabled 布尔 是否为作业启用排队。

工作。日程

Type: Map

定时计划配置用于定期执行作业。

Key 类型 Description
quartz_cron_expression String 使用 Quartz 语法的 Cron 表达式,用于指定任务的运行时间。 例如, 0 0 9 * * ? 每天上午 9:00 UTC 运行作业。
timezone_id String 计划安排所用的时区。 例如,America/Los_Angeles 或 UTC。
pause_status String 计划是否暂停。 有效值: PAUSED, UNPAUSED。

工作。触发器

Type: Map

事件驱动作业执行的触发器配置。

Key 类型 Description
file_arrival Map 基于文件到达的触发器。 请参阅 file_arrival。
table Map 基于表的触发器。 请参阅 表。
table_update Map 基于表更新的触发器。 请参阅 table_update。
periodic Map 定期触发器。 请参阅 定期。
pause_status String 无论触发器是否暂停。 有效值: PAUSED, UNPAUSED。

job.trigger.file_arrival

Type: Map

根据文件到达事件进行配置触发。

Key 类型 Description
url String 要监视新文件的文件路径。
min_time_between_triggers_seconds Integer 触发器事件之间的最短时间(以秒为单位)。
wait_after_last_change_seconds Integer 在触发前最后一个文件更改后的等待时间(以秒为单位)。

job.trigger.table(工作触发器。表格)

Type: Map

基于表的触发器配置。

Key 类型 Description
table_names Sequence 要监视的表名列表。
condition String 触发作业必须满足的 SQL 条件。

job.trigger.table_update

Type: Map

基于表更新的触发配置。

Key 类型 Description
table_names Sequence 要监视更新的表名列表。
condition String 触发作业必须满足的 SQL 条件。
wait_after_last_change_seconds Integer 在最新一次的表更新后触发之前的等待时间(以秒为单位)。

工作。触发。周期性

Type: Map

定时触发配置。

Key 类型 Description
interval Integer 定期触发器的间隔值。
unit String 间隔的时间单位。 有效值:HOURS、、DAYSWEEKS.

工作。触发点

Type: Sequence

这份工作附带的触发因素列表。 当任何激活触发值被评估为真时,运行开始。 每个物品必须设定一个触发类型。 不能与遗留schedule的 、 或triggercontinuous字段在同一请求中设置。

在Databricks CLI版本1.13.0中添加

列表中的每个项目都是一个触发条件:

Key 类型 Description
continuous Map (Beta)连续触发配置。
在Databricks CLI版本1.13.0中添加
file_arrival Map (测试版)文件到达触发配置。
在Databricks CLI版本1.13.0中添加
pause_status String (测试版)这个触发是否被暂停了。 默认状态为 UNPAUSED 未设定状态。 有效值为 UNPAUSED 和 PAUSED。
在Databricks CLI版本1.13.0中添加
periodic Map (Beta)周期性触发配置。
在Databricks CLI版本1.13.0中添加
schedule Map (测试版)克朗计划触发配置。
在Databricks CLI版本1.13.0中添加
table_update Map (测试版)表更新触发配置。
在Databricks CLI版本1.13.0中添加

job.webhook_notifications

Type: Map

作业运行的 Webhook 通知设置。

Key 类型 Description
on_start Sequence 在运行开始时需要通知的 Webhook 通知 ID 列表。
on_success Sequence 运行成功时要通知的 Webhook 通知 ID 的列表。
on_failure Sequence 运行失败时要通知的 Webhook 通知 ID 的列表。
on_duration_warning_threshold_exceeded Sequence 当运行持续时间超过警告阈值时要通知的 Webhook 通知 ID 的列表。
on_streaming_backlog_exceeded Sequence 当任何流超出任何流积压工作阈值时要调用的系统通知 ID 的列表。 可以使用以下指标在health字段中设置流式积压工作阈值:STREAMING_BACKLOG_BYTES、STREAMING_BACKLOG_RECORDS或STREAMING_BACKLOG_SECONDSSTREAMING_BACKLOG_FILES。 警报基于这些指标的 10 分钟平均值。 如果问题仍然存在,则每 30 分钟重新发送一次通知。 最多可以指定 3 个目标。
on_maintenance_start Sequence 一个可选的系统通知ID列表,用于在平台发起的维护开始时调用,用于持续作业。 最多可为 on_maintenance_start 属性指定 3 个目标。
在Databricks CLI版本1.20.0中添加的
on_maintenance_complete Sequence 一个可选的系统通知ID列表,用于平台发起的维护完成时调用,用于连续作业。 最多可为 on_maintenance_complete 属性指定 3 个目标。
在Databricks CLI版本1.20.0中添加的

Examples

以下示例定义了一个资源键为 hello-job 的作业,其中包含一个笔记本任务:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          notebook_task:
            notebook_path: ./hello.py

以下示例使用 SQL 笔记本定义作业:

resources:
  jobs:
    job_with_sql_notebook:
      name: 'Job to demonstrate using a SQL notebook with a SQL warehouse'
      tasks:
        - task_key: notebook
          notebook_task:
            notebook_path: ./select.sql
            warehouse_id: 799f096837fzzzz4

有关其他作业配置示例,请参阅 作业配置。

有关定义作业任务和替代作业设置的信息,请参阅:

job_run

Type: Map

job_run资源作为捆绑部署的一部分触发了现有作业的运行。 与定义作业的 作业不同,作业运行通过ID引用已有的作业。

声明式自动化捆绑包的 Python 支持作业运行。 参见 databricks.bundles.job_runs。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义作业运行。

在Databricks CLI版本1.7.0中添加

job_runs:
  <job_run-name>:
    <job_run-field-name>: <job_run-field-value>
Key 类型 Description
job_id Integer 必填。 要运行的作业的 ID。
在Databricks CLI版本1.7.0中添加
job_parameters Map 运行中使用的作业级参数,例如 param: overriding_val。
在Databricks CLI版本1.7.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.7.0中添加
only Sequence 要在其中运行的任务密钥的列表。 如果未提供该字段,则执行作业中的所有任务。
任务键前缀为 + “也运行其上游任务”,或 + 以“后缀”表示同时执行下游任务。 比如,运行 +my_taskmy_task 和它的上游所有东西,运行 my_task+my_task 和所有下游,然后 +my_task+ 两者都运行。 任务键如果没有, + 只运行该任务。
在Databricks CLI版本1.7.0中添加
performance_target String 无服务器作业上的性能模式。 性能目标确定运行时的计算性能或成本效益水平,并覆盖作业级别定义的性能目标。 有效值为 STANDARD,支持无服务器工作负载的成本效益高执行,以及 PERFORMANCE_OPTIMIZED,通过快速扩展和优化集群性能优先提升启动和执行时间。
在Databricks CLI版本1.7.0中添加
pipeline_params Map 运行中流水线任务的刷新设置。 参见 job_run.pipeline_params。
在Databricks CLI版本1.7.0中添加
queue Map 运行的队列设置。 设置为 enabled 以 true 启用运行队列。
在Databricks CLI版本1.7.0中添加

job_run.pipeline_params

Type: Map

运行中流水线任务的刷新设置。

在Databricks CLI版本1.7.0中添加

Key 类型 Description
full_refresh 布尔 是否触发Spark声明式流水线的全面刷新。
在Databricks CLI版本1.7.0中添加
full_refresh_selection Sequence 一份需要通过全面刷新更新的表格列表。
在Databricks CLI版本1.7.0中添加
refresh_flow_selection Sequence 流程名称用于选择性刷新。 这些与其他选择性刷新选项 refresh_selection 和 full_refresh_selection结合,以确定最终需要刷新的流集合。
在Databricks CLI版本1.7.0中添加
refresh_selection Sequence 一份无需完全刷新即可更新的表格列表。
在Databricks CLI版本1.7.0中添加
reset_checkpoint_selection Sequence 一份可在不清除数据的情况下重置检查点的流流列表。
在Databricks CLI版本1.7.0中添加

Example

以下示例触发了对已有作业的运行,覆盖了一个作业参数,并将运行限制为单个任务及其上游任务:

resources:
  job_runs:
    my_job_run:
      job_id: 123456789
      job_parameters:
        catalog: main
      only:
        - +my_task

materialization_set

重要

此功能以个人预览版提供。 若要试用,请联系 Azure Databricks 联系人。

Type: Map

materialization_set资源允许你在一个捆绑中定义物质化集。 物质化集会产生特征数据。 它列出了要实现的功能视图,以及每个功能 视图 的离线或在线商店。 Azure Databricks 负责创建和管理填充这些存储的 Lakeflow 管道。 有关具体化特征的信息,请参见 “实体化特征视图”。

每条条目 materialized_features 都是该套装中一个具象化的特色成员。 功能视图为每个目的地贡献一名成员,因此同时实现线下和在线的功能视图会被声明为两个实体化功能。 带 sawtooth 窗口的特征视图贡献了三项。 参见 规则:物质化集合必须满足。 将成员分组到一个集合中,会让 Azure Databricks 知道它们可以一起计算,因此它会将它们打包到最少的表和 Lakeflow 流水线中。 有关教程,请参见 “使用声明式自动化捆绑包管理功能视图”。

声明式自动化捆绑包的 Python 支持实体化集。 请看 databricks.bundles.materialization_sets。

Note

该资源需要直接部署引擎。 参见 资源兼容性。

在Databricks CLI版本1.24.0中添加

materialization_sets:
  <materialization_set-name>:
    materialized_features:
      - <materialized_feature-field-name>: <materialized_feature-field-value>
Key 类型 Description
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.24.0中添加
materialized_features Sequence 必填。 每个功能视图和目的地各有一组成员。 参见 materialization_set.materialized_features。
在Databricks CLI版本1.24.0中添加

materialization_set.materialized_featuress

Type: Sequence

其中一个成员是:它实现的特征视图、其数据写入的存储以及刷新方式。 设定恰好一个 offline_store_config 或 online_store_config,最多一个触发点。

在Databricks CLI版本1.24.0中添加

Key 类型 Description
budget_policy_id String 实现管道的预算政策就是被反对的。 请参阅 使用无服务器使用策略的属性使用情况。
在Databricks CLI版本1.24.0中添加
cron_schedule_trigger Map 让议员重新安排日程。 参见 materialization_set.materialized_features.cron_schedule_trigger。
在Databricks CLI版本1.24.0中添加
feature_name String 必填。 特征视图的三级Unity目录名称将实现。 使用对同一捆绑中声明的特征视图的引用,例如 ${resources.features.<feature-name>.full_name},这样捆绑包在实现它的集合之前创建了特征视图。
在Databricks CLI版本1.24.0中添加
offline_store_config Map 将功能数据写入Unity目录表,用于训练和批量评分。 参见 materialization_set.materialized_features.offline_store_config。
在Databricks CLI版本1.24.0中添加
online_store_config Map 将功能数据写入在线商店以实现低延迟服务。 请参见 materialization_set.materialized_features.online_store_config。
在Databricks CLI版本1.24.0中添加
streaming_mode Map 从流媒体源持续刷新成员。 参见 materialization_set.materialized_features.streaming_mode。
在Databricks CLI版本1.24.0中添加
table_trigger Map 当成员的源表发生变化时刷新。
在Databricks CLI版本1.24.0中添加
tags Map 标签应用到具象化的特征上。
在Databricks CLI版本1.24.0中添加

materialization_set.materialized_features.offline_store_config

Type: Map

离线功能表写入的Unity Catalog位置。 这些密钥在写时被接受,读时不会返回。

在Databricks CLI版本1.24.0中添加

Key 类型 Description
catalog_name String 必填。 用目录写离线表。
在Databricks CLI版本1.24.0中添加
schema_name String 必填。 写离线表的模式。
在Databricks CLI版本1.24.0中添加
table_name_prefix String 必填。 生成的表名称的前缀。 Azure Databricks 会附加后缀,因此表被命名<table_name_prefix>_<suffix><table_name_prefix>为 。
在Databricks CLI版本1.24.0中添加

materialization_set.materialized_features.online_store_config

Type: Map

功能数据发布到的在线商店。 有关在线商店的信息,请参见 Databricks在线功能商店。

在Databricks CLI版本1.24.0中添加

Key 类型 Description
catalog_name String 必填。 在线表格目录。 写入时接受,读时未退回。
在Databricks CLI版本1.24.0中添加
online_store_name String 必填。 发布的在线商店名称。
在Databricks CLI版本1.24.0中添加
schema_name String 必填。 在线表格的结构。 写入时接受,读时未退回。
在Databricks CLI版本1.24.0中添加
table_name_prefix String 必填。 生成的在线表名称前缀,Azure Databricks 会在后缀后附加。 写入时接受,读时未退回。
在Databricks CLI版本1.24.0中添加

materialization_set.materialized_features.cron_schedule_trigger

Type: Map

让会员重新安排时间表。

在Databricks CLI版本1.24.0中添加

Key 类型 Description
cron_expression String 一个Quartz cron 表达式,例如 0 0 * * * ?。 当 mode 时 MANUAL是必需的,且当 时 DERIVED不可设置mode。
在Databricks CLI版本1.24.0中添加
mode String 有效的数值为 MANUAL,使用 你提供的 ,cron_expression和 DERIVED,其中 Azure Databricks 从功能定义中选择调度。 Databricks 推荐 DERIVED,该流程在每个窗口预计到达所需的数据到达后运行流水线。 DERIVED 不支持 column_selection 在某个 sdp_source,或 last 仅 rolling 在在线商店中出现的窗口聚合。 这些需要 MANUAL。
在Databricks CLI版本1.24.0中添加
timezone_id String 评估时间表的时区。 默认为 UTC。 当 mode 时 DERIVED, timezone_id 如果 设,则必须为 UTC。
在Databricks CLI版本1.24.0中添加

materialization_set.materialized_features.streaming_mode

Type: Map

持续从流媒体中刷新成员。 集合为 streaming_mode 的成员不取 cron_schedule_trigger。

在Databricks CLI版本1.24.0中添加

Key 类型 Description
freshness_target String 具体化数据被允许多久变得陈旧,时长如 60s。
在Databricks CLI版本1.24.0中添加
mode String 有效数值适用于 STREAMING_MODE_TYPE_RTM 实时物料化和 STREAMING_MODE_TYPE_MBM 微批量物料化。
STREAMING_MODE_TYPE_MBM 不可用。 使用 STREAMING_MODE_TYPE_RTM。
在Databricks CLI版本1.24.0中添加

物质化集合必须满足的规则

除非满足以下所有条件,否则创建请求会被拒绝:

  • 集合中的每个特征视图都指定相同的离线目的地和相同的在线目的地。 集合写入一个离线目的地,也可以写入一个在线目的地,因此具有不同离线或在线目的地的功能视图应属于不同的集合。
  • 该套装不会将批量实体化的特色视图与流媒体模式下实体化的功能视图混合使用。 带 sawtooth 窗口的流式功能视图是例外。 它的批量和流媒体实体化版本属于同一套。
  • 功能视图的离线和在线目的地配置至少在 catalog_name、 schema_name或 table_name_prefix中有一个不同。
  • 使用 sawtooth 窗口进行聚合的功能视图恰好贡献三个具体化功能成员:一个离线实体化功能、一个在线实体化功能和一个在线流媒体实现功能。 cron_schedule_trigger批量离线和批量在线实现特征必须设置为 DERIVED,批量在线和流式在线实体化特征必须使用相同的在线目的地配置。声明三个具体化特征中的一个子集将被拒绝。

由于捆绑中的特征视图是在实现它们的实体化集之前创建的,因此因上述原因被拒绝的集合会保留其特征视图。 跑去 databricks bundle destroy 移除它们,或者纠正设置后重新部署。

改变物质化集

API解析并应用在提供的物质化集中所做的更改。 下表描述了每种配置变更在 databricks bundle deploy上的作用,在替换或删除集合前会请求确认,且未经您的批准 --auto-approve不得继续。

找零 Result
移除集合内属于同一特征视图的所有实体化特征成员 原地申请。 物质化集合中剩余的实体化特征保持其身份和物质化数据。
在一组特征视图中移除部分但非全部实体化特征成员 已拒绝。 删除功能视图的离线实体化特征会连锁到其在线实体化的功能,因此所有该特征视图的实体化特征必须一起移除。
向现有集合添加具象化特征成员 更换了布景。 其所有具象化特征都会被摧毁并重新计算,包括那些构型未变的成员。
更改任何实体化特征成员的任意键,包括触发器, tags或 budget_policy_id 更换了布景。 其所有具象化特征都会被摧毁并重新计算,包括那些构型未变的成员。
无需更改配置即可重新部署 无操作。

Example

以下示例体现了线下和线上均有一个功能视图。 feature_name特征视图在同一捆包中声明的引用,使得该捆绑包先创建了特征视图。 这两个目的地使用不同的前缀,服务器需要这些前缀。

YAML
resources:
  materialization_sets:
    transactions:
      materialized_features:
        - feature_name: ${resources.features.transaction_count.full_name}
          offline_store_config:
            catalog_name: ${var.catalog}
            schema_name: ${var.schema}
            table_name_prefix: transaction_count_offline
          cron_schedule_trigger:
            mode: DERIVED
        - feature_name: ${resources.features.transaction_count.full_name}
          online_store_config:
            online_store_name: ${var.online_store}
            catalog_name: ${var.catalog}
            schema_name: ${var.schema}
            table_name_prefix: transaction_count_online
          cron_schedule_trigger:
            mode: DERIVED
Python
def load_resources(bundle: Bundle) -> Resources:
    resources = Resources()

    resources.add_materialization_set(
        'transactions',
        MaterializationSet(
            materialized_features=[
                MaterializedFeature(
                    feature_name='${resources.features.transaction_count.full_name}',
                    offline_store_config=OfflineStoreConfig(
                        catalog_name='${var.catalog}',
                        schema_name='${var.schema}',
                        table_name_prefix='transaction_count_offline',
                    ),
                    cron_schedule_trigger=CronSchedule(mode=CronScheduleMode.DERIVED),
                ),
                MaterializedFeature(
                    feature_name='${resources.features.transaction_count.full_name}',
                    online_store_config=OnlineStoreConfig(
                        online_store_name='${var.online_store}',
                        catalog_name='${var.catalog}',
                        schema_name='${var.schema}',
                        table_name_prefix='transaction_count_online',
                    ),
                    cron_schedule_trigger=CronSchedule(mode=CronScheduleMode.DERIVED),
                ),
            ]
        ),
    )

    return resources

mcp_service

Type: Map

MCP服务资源允许你在捆绑中定义 MCP服务 。 MCP 服务通过 Unity 目录连接注册外部模型上下文协议(MCP)服务器,并通过 AI 网关暴露其工具。

声明式自动化捆绑包的 Python 支持 MCP 服务。 请看 databricks.bundles.mcp_services。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义MCP服务。

在Databricks CLI版本1.17.0中添加

mcp_services:
  <mcp_service-name>:
    <mcp_service-field-name>: <mcp_service-field-value>
Key 类型 Description
comment String 对MCP服务的评论或描述。
在Databricks CLI版本1.17.0中添加
config Map MCP服务的操作配置。 将源引用、工具选择器和速率限制分组,这些参数配置了调用时MCP服务的行为。 参见 mcp_service.config。
在Databricks CLI版本1.17.0中添加
grants Sequence 与MCP服务相关的资助。 请参阅 授予。
在Databricks CLI版本1.17.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.17.0中添加
mcp_service_id String 必填。 用于MCP服务的ID。 这成为服务资源名称的最后一个组件。
在Databricks CLI版本1.17.0中添加
parent String 必填。 用于创建MCP服务的Unity Catalog模式,格式为 schemas/{catalog}.{schema}。
在Databricks CLI版本1.17.0中添加

mcp_service.config

Type: Map

MCP服务的操作配置。 将源引用、工具选择器和速率限制分组,这些参数配置了调用时MCP服务的行为。

在Databricks CLI版本1.17.0中添加

Key 类型 Description
include_tool_selectors Sequence 工具名称或前缀模式,从MCP服务器中暴露。 使用精确的工具名称或前缀模式,如 read_*。 空列表公开所有工具。 最多允许1,024个选择器,每个选择器最多可包含256个字符。
在Databricks CLI版本1.17.0中添加
rate_limits Sequence 工具调用的速率限制。 默认支持的范围包括用户、组、服务主体、整个服务以及每个用户。 支持请求和令牌限制。 当没有设置速率限制时,就是空的。
在Databricks CLI版本1.17.0中添加
source_connection Map Unity 目录连接,引用 MCP 服务器。 创建时必需。
在Databricks CLI版本1.17.0中添加

Example

resources:
  mcp_services:
    my_mcp:
      parent: schemas/main.default
      mcp_service_id: test_mcp_1
      comment: 'Points at a Unity Catalog connection hosting an MCP server'
      config:
        source_connection:
          name: connections/main.default.mcp_conn_1

模型(遗产)

Type: Map

模型资源允许在捆绑包中定义 旧模型 。 Databricks 建议改用 Unity 目录 注册的模型 。

model_provider_service

Type: Map

模型提供者服务资源允许您在捆绑中定义 模型提供者服务 。 模型提供者服务通过 AI 网关配置认证和路由到外部模型提供商,如 OpenAI、Azure OpenAI、Anthropic 或 Amazon Bedrock。

Python 声明式自动化捆包支持模型提供者服务。 参见 databricks.bundles.model_provider_services。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义模型提供者服务。

在Databricks CLI版本1.17.0中添加

model_provider_services:
  <model_provider_service-name>:
    <model_provider_service-field-name>: <model_provider_service-field-value>
Key 类型 Description
comment String 对模型提供者服务的评论或描述。
在Databricks CLI版本1.17.0中添加
config Map 模型提供者服务的行为配置:提供者认证和提供者特定字段、该提供者服务可路由的模型目录,以及控制请求头部、查询参数和非管理子路径如何跨越信任边界到上游提供者的直通策略。 参见 model_provider_service.config。
在Databricks CLI版本1.17.0中添加
grants Sequence 与模型提供者服务相关的资助。 请参阅 授予。
在Databricks CLI版本1.17.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.17.0中添加
model_provider_service_id String 必填。 用于模型提供者服务的ID。 这成为服务资源名称的最后一个组件。
在Databricks CLI版本1.17.0中添加
parent String 必填。 用于创建模型提供者服务的Unity Catalog模式,格式为 schemas/{catalog}.{schema}。
在Databricks CLI版本1.17.0中添加

model_provider_service.config

Type: Map

模型提供者服务的行为配置。

在Databricks CLI版本1.17.0中添加

Key 类型 Description
allow_all_targets 布尔 当为真时,接受上游提供者暴露的任何模型; targets 不强制且不限制路由性。 如果错误,只有中 targets 列的模型才可路由。 默认值为 false。
在Databricks CLI版本1.17.0中添加
amazon_bedrock Map 亚马逊基石提供商配置。
在Databricks CLI版本1.17.0中添加
anthropic Map Anthropic 提供者配置。 必须在创建中恰好有一个directrelayed或;两者互斥。
在Databricks CLI版本1.17.0中添加
azure_openai Map Azure OpenAI 提供者配置.
在Databricks CLI版本1.17.0中添加
bedrock_mantle Map 亚马逊基石提供商配置。
在Databricks CLI版本1.21.0中添加
custom Map 自定义兼容 OpenAI 的提供者配置。
在Databricks CLI版本1.17.0中添加
forward_headers 布尔 是否将收到的HTTP头转发给上游提供者。 默认为false,并且是针对整个提供者服务配置的,而不是每个请求。 上游认证在提供者特定配置中单独配置。
在Databricks CLI版本1.17.0中添加
forward_query_parameters 布尔 是否转发到上游的查询参数。 默认为false,并且是针对整个提供者服务配置的,而不是每个请求。
在Databricks CLI版本1.17.0中添加
forward_unmanaged_paths 布尔 是否代理 AI Gateway 不识别为配置的提供者原生 API 类型的路径。 默认值为 false。 当这些路径成立时,这些路径会被不更改地转发给上游提供者。 当错误时,只提供已识别的API路径。 启用此功能拓宽了通过提供者服务暴露的上游API表面。 AI 网关无法评估不透明的未管理请求的服务策略,因此只要服务策略附加到该安全请求上,未管理请求都会被拒绝。
在Databricks CLI版本1.17.0中添加
gemini_enterprise Map Gemini Enterprise 服务提供商配置。
在Databricks CLI版本1.17.0中添加
inference_table Map 针对直接发送给该服务提供商服务的请求进行有效载荷日志配置。 通过模型服务路由的请求则被该模型服务的推理表捕获。
在Databricks CLI版本1.17.0中添加
microsoft_foundry Map Microsoft Foundry 提供者配置。
在Databricks CLI版本1.17.0中添加
openai Map OpenAI 提供商配置。
在Databricks CLI版本1.17.0中添加
pricing Map 该服务提供者的定价配置。 包含 default_discount_basis_points,对外部模型支出估计(基点)进行全提供者范围的调整(例如, 2000 偏差20%,且 -2000 加价20%)。 在创建和更新时,显式为空的配置会被保留,且不施加任何调整。
在Databricks CLI版本1.21.0中添加
provider_type String 外部模型供应商。 创建时必须,之后不可更改。 设置匹配的提供者特定配置,如 openai、 azure_openai或 amazon_bedrock。 有效值为 EXTERNAL_MODEL_PROVIDER_TYPE_OPENAI、、EXTERNAL_MODEL_PROVIDER_TYPE_AZURE_OPENAI、EXTERNAL_MODEL_PROVIDER_TYPE_ANTHROPIC、、EXTERNAL_MODEL_PROVIDER_TYPE_AMAZON_BEDROCKEXTERNAL_MODEL_PROVIDER_TYPE_CUSTOMEXTERNAL_MODEL_PROVIDER_TYPE_MICROSOFT_FOUNDRY、 EXTERNAL_MODEL_PROVIDER_TYPE_GEMINI_ENTERPRISE和 EXTERNAL_MODEL_PROVIDER_TYPE_BEDROCK_MANTLE。
在Databricks CLI版本1.17.0中添加
rate_limits Sequence 直接发送给该服务提供商服务的请求的速率限制。 通过模型服务路由的请求则使用该模型服务的速率限制。
在Databricks CLI版本1.17.0中添加
targets Sequence 该提供者服务暴露的模型和提供者原生API类型。 每个条目必须包含至少一个 native_api_types 值。 当 allow_all_targets 为假时,至少需要一个条目,且模型服务目的地只能引用列出的型号。 当 为真时 allow_all_targets ,任何上游模型都可以路由;该列表中的条目提供 API 类型的元数据,而不限制其他模型。
在Databricks CLI版本1.17.0中添加

Example

resources:
  model_provider_services:
    my_model_provider_service:
      parent: schemas/main.myschema
      model_provider_service_id: myservice
      comment: comment1
      config:
        provider_type: EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
        targets:
          - model: gpt-4o
            native_api_types:
              - openai/v1/chat/completions
        custom:
          direct:
            base_url: https://api.example.com/v1
            api_key:
              plaintext: my-api-key

model_service

Type: Map

模型服务资源允许你在捆绑包中定义 模型服务 。 模型服务是一个受管控的AI网关端点,将请求路由到一个或多个目的地,例如模型提供者服务或Databricks基础模型。

声明式自动化捆绑包的 Python 支持模型服务。 请看 databricks.bundles.model_services。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义模型服务。

在Databricks CLI版本1.17.0中添加

model_services:
  <model_service-name>:
    <model_service-field-name>: <model_service-field-value>
Key 类型 Description
comment String 对模型服务的评论或描述。
在Databricks CLI版本1.17.0中添加
config Map 操作配置环绕模型服务资源。 参见 model_service.config。
在Databricks CLI版本1.17.0中添加
grants Sequence 与示范服务相关的资助。 请参阅 授予。
在Databricks CLI版本1.17.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.17.0中添加
model_service_id String 必填。 用于模型服务的ID。 这成为服务资源名称的最后一个组件。
在Databricks CLI版本1.17.0中添加
parent String 必填。 创建模型服务的Unity Catalog模式,格式为 schemas/{catalog}.{schema}。
在Databricks CLI版本1.17.0中添加

model_service.config

Type: Map

操作配置环绕模型服务资源。

在Databricks CLI版本1.17.0中添加

Key 类型 Description
inference_table Map 有效载荷日志推理表配置。
在Databricks CLI版本1.17.0中添加
rate_limits Sequence 速率限制适用于通过该模型服务路由的请求。
在Databricks CLI版本1.17.0中添加
routing Map 路由配置:目的地与备份。
在Databricks CLI版本1.17.0中添加

Examples

resources:
  model_services:
    my_model_service:
      parent: schemas/main.default
      model_service_id: test_ms_1
      comment: 'Routes chat traffic to a foundation model'
      config:
        routing:
          destinations:
            - name: primary
              destination_type: DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL
              pay_per_token_config:
                model: models/system.ai.databricks-gpt-5
              traffic_percentage: 100

model_serving_endpoint

Type: Map

model_serving_endpoint资源允许定义 模型服务终结点。 请参阅管理模型服务终结点。

Python 声明式自动化捆绑包支持模型服务端点。 请参见 databricks.bundles.model_serving_endpoints。

model_serving_endpoints:
  <model_serving_endpoint-name>:
    <model_serving_endpoint-field-name>: <model_serving_endpoint-field-value>
Key 类型 Description
ai_gateway Map 服务终结点的 AI 网关配置。 注意:目前仅支持外部模型和预配的吞吐量终结点。 请参阅 ai_gateway。
在Databricks CLI版本0.230.0中添加
budget_policy_id String 要用于此终结点的预算策略的 ID。
在Databricks CLI版本0.244.0中添加
config Map 服务终结点的核心配置。 请参阅 配置。
description String 服务终结点的说明。
在Databricks CLI版本0.260.0中添加
email_notifications Map 服务终结点的电子邮件通知配置。 请参阅 email_notifications。
新增于 Databricks CLI 0.264.0 版本
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 服务终结点的名称。 此字段是必需的,并且必须在 Databricks 工作区中是唯一的。 终结点名称可以包含字母数字字符、短划线和下划线。
permissions Sequence 模型服务终结点的权限。 查看 权限。
rate_limits Sequence Deprecated. 要应用于服务终结点的速率限制。 使用 AI 网关管理速率限制。
route_optimized 布尔 为服务终结点启用路由优化。
tags Sequence 要附加到服务终结点并自动传播到计费日志的标记。
telemetry_config Map 将端点遥测(日志、追踪和指标)持久化到Unity Catalog表的配置。 请看 telemetry_config。
在Databricks CLI版本1.6.0中添加

model_serving_endpoint.telemetry_config

Type: Map

将端点遥测(日志、追踪和指标)持久化到Unity Catalog表的配置。

在Databricks CLI版本1.6.0中添加

Key 类型 Description
enabled_telemetry_features Sequence 该端点启用遥测信号。 如果为空或省略,所有信号都被启用;否则只有列出的信号被启用。
在Databricks CLI版本1.14.0中添加
inference_table_config Map 推理表有效载荷日志的配置,包括采样。
在Databricks CLI版本1.6.0中添加
table_names Map Unity 目录表,端点遥测数据(日志、跟踪和指标)被导出到这里。 提供此功能即可从给定的表中为端点创建新的遥测配置文件。
在Databricks CLI版本1.10.0中添加
telemetry_profile_id String 一个现有遥测配置文件的ID,用于该端点。 提供此功能以重用已创建的遥测配置文件,而不是指定 table_names。
在Databricks CLI版本1.10.0中添加

model_serving_endpoint.email_notifications

Type: Map

服务终结点的电子邮件通知配置。

Key 类型 Description
on_update_failure Sequence 终结点无法更新其配置或状态时要通知的电子邮件地址列表。
on_update_success Sequence 终结点成功更新其配置或状态时要通知的电子邮件地址列表。

model_serving_endpoint.ai_gateway

Type: Map

服务终结点的 AI 网关配置。

Key 类型 Description
fallback_config Map 如果对服务实体的请求失败并出现某些错误代码,则流量回退的配置会自动回退到其他服务实体,以提高可用性。 请参阅 fallback_config。
guardrails Map 护栏配置。 请参阅 护栏。
inference_table_config Map 配置用于将推理日志记录到 Unity 目录表。 请参阅 inference_table_config。
rate_limits Sequence 限流配置。
usage_tracking_config Map 用于跟踪使用情况的配置。 请参阅 usage_tracking_config。

model_serving_endpoint.ai_gateway.fallback_config

Type: Map

配置流量回退,如果请求失败并出现某些错误代码,则自动回退到其他服务实体。

Key 类型 Description
enabled 布尔 是否为此终结点启用回退。

model_serving_endpoint.ai_gateway.guardrails

Type: Map

AI 网关防护配置。

Key 类型 Description
input Map 输入护栏配置,字段如下所示safetypii。
output Map 输出防护栏配置,字段如下所示safetypii。
invalid_keywords Sequence 要阻止的关键字列表。

model_serving_endpoint.ai_gateway.inference_table_config

Type: Map

配置用于将推理日志记录到 Unity 目录表。

Key 类型 Description
catalog_name String Unity 目录中目录的名称。
schema_name String Unity 目录中架构的名称。
table_name_prefix String 推断表名的前缀。
enabled 布尔 是否启用推理表日志。

model_serving_endpoint.ai_gateway.usage_tracking_config

Type: Map

用于跟踪使用情况的 AI 网关配置。

Key 类型 Description
enabled 布尔 是否启用使用情况跟踪。

model_serving_endpoint.config

Type: Map

服务终结点的核心配置。

Key 类型 Description
served_entities Sequence 用于终结点服务的实体列表。 每个服务实体都包含字段,例如entity_name、entity_version、workload_size、scale_to_zero_enabledworkload_typeenvironment_vars。
served_models Sequence (已弃用:改用 served_entities )终结点要提供服务的模型列表。
traffic_config Map 定义如何将调用请求路由到服务终结点的流量配置。 请参阅 traffic_config。

model_serving_endpoint.config.traffic_config

Type: Map

定义如何将调用请求路由到服务终结点的流量配置。

Key 类型 Description
routes Sequence 用于流量分配的路由列表。 每个路由都包含 served_model_name 和 traffic_percentage。

Example

以下示例定义了 Unity Catalog 模型服务终结点:

resources:
  model_serving_endpoints:
    uc_model_serving_endpoint:
      name: 'uc-model-endpoint'
      config:
        served_entities:
          - entity_name: 'myCatalog.mySchema.my-ads-model'
            entity_version: '10'
            workload_size: 'Small'
            scale_to_zero_enabled: 'true'
        traffic_config:
          routes:
            - served_model_name: 'my-ads-model-10'
              traffic_percentage: '100'
      tags:
        - key: 'team'
          value: 'data science'

管道

Type: Map

使用管道资源可以创建 管道。

声明式自动化捆绑包的 Python 支持管道。 请参阅 databricks.bundles.pipelines。

有关管道的信息,请参见 Lakeflow上的Spark声明式管道。 有关使用声明性自动化捆绑包模板创建管道的教程,请参阅 使用声明性自动化捆绑包开发管道。

pipelines:
  <pipeline-name>:
    <pipeline-field-name>: <pipeline-field-value>
Key 类型 Description
allow_duplicate_names 布尔 如果为 false,则名称与其他管道的名称冲突时,部署将失败。
在Databricks CLI版本0.261.0中添加
budget_policy_id String 此管道的预算政策。
在Databricks CLI版本0.230.0中添加
cascade_on_destroy 布尔 销毁流水线是否也会删除其数据集(具体化视图、流表和视图)。 当服务器未设置时,服务器默认值生效。 设置为 以 false 保留销毁时的数据集。 支持直接部署引擎。
在Databricks CLI版本1.12.0中添加
catalog String Unity Catalog 中要将数据从此管道发布到的目录。 如果指定了target,此管道中的表将在target中的catalog架构内发布(例如 catalog.target.table)。 如果未 target 指定,则不会将任何数据发布到 Unity 目录。
channel String Lakeflow 管道发布通道,指定要使用的 Lakeflow 管道版本。
clusters Sequence 此管道部署的群集设置。 适用于经典(非无服务器)管道。 当 serverless 是 true时省略该字段。 请参阅 群集。
configuration Map 此管道执行的配置。
deployment Map 此管道的部署类型。 请参阅 部署。
dry_run 布尔 管道是否为干运行管道。
edition String 管道产品版本。
environment Map 此管道的环境规范,用于在无服务器计算上安装依赖项。 查看 环境。 此密钥仅在 Databricks CLI 版本 0.258 及更高版本中受支持。
在Databricks CLI版本0.257.0中添加
event_log Map 此管道的事件日志配置。 请参阅 event_log。
在Databricks CLI版本0.246.0中添加
filters Map 该筛选器用于确定要包含在已部署图形中的管道包。 请参阅 筛选器。
gateway_definition Map 网关管道的配置。 这些设置不能与设置一起使用 ingestion_definition 。
id String 此管道的唯一标识符。
ingestion_definition Map 托管引入管道的配置。 这些设置不能与libraries、schema、target或catalog设置一起使用。 请参阅 ingestion_definition。
libraries Sequence 此部署所需的库或代码列表。 请参阅 pipeline.libraries。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 此管道的易记名称。
notifications Sequence 此管道的通知设置。 请参阅 通知。
parameters Map 流水线执行的默认参数,每个键是参数名称,值为参数值。 JSON格式的最大总大小为10,000字符。
permissions Sequence 管道的权限。 查看 权限。
photon 布尔 是否为此管道启用了 Photon。 如果 serverless 设置为 true,则忽略此键。
restart_window Map 定义此管道的重启窗口。 可以在此窗口中重启管道,而无需落后。
root_path String 此管道的根路径。 在 Databricks 用户界面中编辑管道时,此目录用作根目录,并在管道执行期间执行Python源时将其添加到 sys.path。
在Databricks CLI版本0.253.0中添加
run_as Map 管道运行时使用的身份。 如果未指定,则管道将以创建它的用户身份运行。 精确指定其中 user_name一个 、 service_principal_name或 group_name。 如果指定多个,则会抛出错误。 参见 “将运行身份设置为组”。
在Databricks CLI版本0.241.0中添加
schema String 作为表的读取来源或发布目标的默认架构(数据库)。
在Databricks CLI版本0.230.0中添加
serverless 布尔 是否为此管道启用了无服务器计算。 Databricks 建议为新管道使用无服务器计算。 将此 true 设置为无服务器计算运行流水线。 对于笔记本或文件流水线,省略该字段使用通过字段 clusters 配置的经典计算。 当 true,省略 clusters。 Photon 始终为无服务器管道启用。
storage String 用于存储检查点和表的 DBFS 根目录。
tags Map 与流水线相关的标签映射。 这些内容作为群集标记转发到群集,因此受到相同的限制。 最多可以向管道添加 25 个标记。
在Databricks CLI版本0.256.0中添加
target String 要将此管道中的表添加到的目标架构(数据库)。 必须指定 schema 或 target 中的一个。 若要发布到 Unity 目录,还指定 catalog。 用于创建管道的此旧字段已弃用,以支持 schema 字段。
usage_policy_id String 用于此管道的无服务器使用策略的 ID。
新增于 Databricks CLI 版本 0.273.0

pipeline.deployment

Type: Map

管道的部署类型配置。

Key 类型 Description
kind String 部署类型。 例如,BUNDLE。
metadata_file_path String 用于部署的元数据文件路径

pipeline.environment

Type: Map

用于在无服务器计算上安装依赖项的环境规范。

Key 类型 Description
dependencies Sequence 此环境中的 pip 版本支持的 pip 依赖项列表。 每个依赖项都是 pip 需求文件中的一行。
environment_version String (公开预览)例如4,用于执行客户 Python 代码的无服务器 Python 环境版本。 每个环境版本都包含特定的 Python 版本和一套经过精心设计的预装库,并定义了版本,提供一个稳定且可复现的执行环境。 Databricks 支持每个环境版本的三年生命周期。 有关可用版本及其包含的包,请参见 环境版本。
在Databricks CLI版本0.294.0中添加

pipeline.event_log

Type: Map

管道的事件日志配置。

Key 类型 Description
catalog String 事件日志被发布在 Unity Catalog 所属的目录下。
name String 在 Unity Catalog 中发布事件日志的名称。
schema String 活动日志发布于 Unity Catalog 架构下。

pipeline.filters

Type: Map

用于确定在已部署图表中需纳入的管道包的筛选器。

Key 类型 Description
include Sequence 要包含的包名称的列表。
exclude Sequence 要排除的包名称的列表。

pipeline.ingestion_definition

Type: Map

托管引入管道的配置。 这些设置不能与libraries、schema、target或catalog设置一起使用。

Key 类型 Description
connection_name String 要用于引入的连接的名称。 若要以编程方式为支持仅限 API 的身份验证的连接器创建连接,请在 databricks connections create 预部署脚本或作业任务中使用。 请参阅 部署。
connector_type String 可选。 源的连接器类型。 有效值为 CDC 和 QUERY_BASED。
在Databricks CLI版本0.296.0中添加
data_staging_options Map 可选。 暂存数据存储的位置。 这需要从包含网关管道的 CDC 托管引入管道迁移到合并的 CDC 托管引入管道。 如果未指定,则会在顶级管道定义中指定的目录和架构/目标中创建暂存数据的卷。
在Databricks CLI版本0.296.0中添加
full_refresh_window Map 可选。 一个窗口,指定 CDC 中快照查询的一组时间范围。
ingest_from_uc_foreign_catalog 布尔 不可变。 如果设置为 true,管道将直接从 Unity 目录外部目录引入表,而无需指定 Unity 目录连接或引入网关。 source_catalog IngestionConfig 对象中的字段被解释为要从中引入的 Unity 目录外部目录。
在Databricks CLI版本0.279.0中添加
ingestion_gateway_id String 引入网关的 ID。
objects Sequence 必填。 指定要复制的表和复制表的目标的设置。 每个对象可以是 SchemaSpec、 TableSpec 或 ReportSpec。
source_type String 使用 source_configurations时必需 。 指定连接器类型(例如,POSTGRESQL)。 MYSQL
source_configurations Sequence 目录级源配置参数。 使用此字段时,还必须指定 source_type。 请参阅 source_configurations。
table_configuration Map 引入表的配置。 请参阅 table_configuration。

SchemaSpec

Type: Map

用于从架构中引入所有表的架构对象规范。

Key 类型 Description
source_schema String 要引入的源架构的名称。
destination_catalog String Unity Catalog 中目标目录的名称。
destination_schema String Unity 目录中的目标架构的名称。
table_configuration Map 应用于该架构中所有表的配置。 请参阅 pipeline.ingestion_definition.table_configuration。

表格规格

Type: Map

用于导入特定表的表对象规范。

Key 类型 Description
source_schema String 包含表的源架构的名称。
source_table String 要引入的源表的名称。
destination_catalog String Unity Catalog 中目标目录的名称。
destination_schema String Unity 目录中的目标架构的名称。
destination_table String Unity Catalog中的目标表名称。
table_configuration Map 此特定表的配置。 请参阅 pipeline.ingestion_definition.table_configuration。

报告规格

Type: Map

用于引入分析报表的报表对象规范。

Key 类型 Description
source_url String 源报表的 URL。
source_report String 源报表的名称或标识符。
destination_catalog String Unity Catalog 中目标目录的名称。
destination_schema String Unity 目录中的目标架构的名称。
destination_table String 报告数据目标表的名称。
table_configuration Map 报表表的配置。 请参阅 pipeline.ingestion_definition.table_configuration。

pipeline.ingestion_definition.source_configurations

Type: Sequence

源的配置。 序列中的每个元素都是包含目录级配置的 Map。

Key 类型 Description
catalog Map 目录级源配置参数。 请参阅 目录。
pipeline.ingestion_definition.source_configurations.catalog

Type: Map

目录级源配置参数

Key 类型 Description
postgres Map 特定于 Postgres 的目录级配置参数。 包含一个slot_config键,该键是一个Map,代表用于逻辑复制的 Postgres 插槽配置。
source_catalog String 源目录名称。

pipeline.ingestion_definition.table_configuration

Type: Map

引入表的配置选项。

有关完整的选项集,包括连接器专用选项,请参见 table_configuration REST API 参考中的 “创建管道” 字段。

Key 类型 Description
auto_full_refresh_policy Map 当管道遇到可通过全刷新解决的问题时,自动运行表的全刷新策略。 如果未指定,则自动全刷新将被禁用。 参见 pipeline.ingestion_definition.table_configuration.auto_full_refresh_policy。
clustering_columns Sequence 用于将目标表聚类的列名列表。 该域与 enable_auto_clustering互斥。 请参阅启用液体聚类。
enable_auto_clustering 布尔 是否在目标表上启用自动液体聚类。 默认为 false。 该域与 clustering_columns互斥。 请参阅启用液体聚类。
exclude_columns Sequence 列出要在数据摄取过程中排除的列名。 未指定时,include_columns 完全控制要引入的列。 指定后,所有其他列(包括未来的列)将自动纳入数据引入过程。 此字段与 include_columns 互斥。
include_columns Sequence 要包含用于引入的列名的列表。 如果未指定,将包含除其中列 exclude_columns 以外的所有列。 将来的列将被自动包含。 指定后,所有其他将来的列将自动排除在引入之外。 此字段与 exclude_columns 互斥。
primary_keys Sequence 用于作为表主键的列名列表。
query_based_connector_config Map 仅适用于基于查询的连接器的配置。 参见 pipeline.ingestion_definition.table_configuration.query_based_connector_config。
row_filter String 一个用于筛选要摄取行的条件。 用 Databricks SQL 语法写入该条件,但不包含 WHERE 关键字。 请参阅 选择要导入的行。
scd_type String 要应用于表的缓慢变化尺寸(SCD)类型。 有效值为:SCD_TYPE_1、SCD_TYPE_2 和 APPEND_ONLY。 默认为 SCD_TYPE_1。 请参阅“启用历史记录跟踪”(SCD 类型 2)。
sequence_by Sequence 指定源数据中事件的逻辑顺序的列名。 Spark 声明性管道使用此排序来处理顺序无序到达的更改事件。
source_metadata_column String 要添加到每个包含每行源元数据的记录中添加的结构体列名称。
table_properties Map 在目标表上设置的表属性,作为键值对。 这些会覆盖 table_properties 管道的集合。 参见 “设置 Delta 表属性”。
pipeline.ingestion_definition.table_configuration.auto_full_refresh_policy

Type: Map

当管道遇到可通过全刷新解决的问题时,自动运行表的全刷新策略。 如果未指定,则自动全刷新将被禁用。 请参阅 自动完全刷新策略。

Key 类型 Description
enabled 布尔 必填。 是否启用自动完全刷新。
min_interval_hours Integer 表上一次完整刷新与新的自动全刷新之间的最短间隔(小时)。 默认为 24。
pipeline.ingestion_definition.table_configuration.query_based_connector_config

Type: Map

仅适用于基于查询的连接器的配置。 参见 基于查询的连接器参考。

Key 类型 Description
cursor_columns Sequence 源表中单调递增列的名称,连接器用于增量读取和摄取表。 数值可以重复,但不能减少。 如果表使用 SCD_TYPE_1 或 SCD_TYPE_2,这些列也会作为 sequence_by ,除非你明确设置 sequence_by 。 请参阅 游标列要求。
deletion_condition String 一个用于识别已被软删除的源行的 SQL 条件,例如 is_deleted = true。 请参阅 “删除条件”。
hard_deletion_sync_min_interval_in_seconds Integer 检测到从源表物理移除的行的主键快照之间的最小间隔(秒)。 如果未设置,则强制删除同步将被禁用。 请参阅 硬删除跟踪。

pipeline.libraries

Type: Sequence

定义此管道所需的库或代码列表。

列表中的每个项都是一个定义:

Key 类型 Description
file Map 定义管道并存储在 Databricks Repos中的文件的路径。 请参阅 pipeline.libraries.file。
glob Map 用于包含源代码的统一字段。 每个条目可以是笔记本路径、文件路径或结束 /**的文件夹路径。 此字段不能与 notebook 或 file 一起使用。 请参阅 pipeline.libraries.glob。
notebook Map 定义管道并存放在 Databricks 工作区的笔记本的路径。 请参阅 pipeline.libraries.notebook。
whl String 此字段已弃用

pipeline.libraries.file

Type: Map

定义管道并存储在 Databricks Repos中的文件的路径。

Key 类型 Description
path String 源代码的绝对路径。

pipeline.libraries.glob

Type: Map

用于包含源代码的统一字段。 每个条目可以是笔记本路径、文件路径或结束 /**的文件夹路径。 此字段不能与 notebook 或 file 一起使用。

Key 类型 Description
include String 要包含管道的源代码

pipeline.libraries.notebook

Type: Map

定义管道并存放在 Databricks 工作区的笔记本的路径。

Key 类型 Description
path String 源代码的绝对路径。

pipeline.通知

Type: Sequence

此管道的通知设置。 序列中的每个项都是通知配置。

Key 类型 Description
alerts Sequence 触发通知的警报列表。 有效值包括on-update-success,,on-update-failure,on-update-fatal-failureon-flow-failure。
email_recipients Sequence 触发配置的警报时要通知的电子邮件地址列表。

Example

以下示例定义了一个具有资源键 hello-pipeline 的管道:

resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

有关其他管道配置示例,请参阅 管道配置。

postgres_branch

重要

此功能在 Beta 版中。

Type:Map

Postgres 分支资源允许在捆绑包中定义 Lakebase 分支 。 还必须定义相应的 Postgres 项目 和 计算终结点。

在Databricks CLI版本0.287.0中添加

postgres_branches:
  <postgres_branch-name>:
    <postgres_branch-field-name>: <postgres_branches-field-value>
Key 类型 Description
branch_id String 用于分支的 ID。 这将成为分支资源名称的最终组件。 ID 是必需的,并且长度必须为 1-63 个字符,以小写字母开头,并且仅包含小写字母、数字和连字符。 例如,development 将变为 projects/my-app/branches/development。
在Databricks CLI版本0.287.0中添加
expire_time String 绝对过期时间戳。 设置后,分支将在此时间过期。
在Databricks CLI版本0.287.0中添加
is_protected 布尔 设置为 true 时,保护分支免遭删除和重置。 当分支受到保护时,无法删除关联的计算终结点和项目。
在Databricks CLI版本0.287.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.287.0中添加
no_expiry 布尔 显式禁用过期。 如果设置为 true,分支将不会过期。 如果设置为 false,则请求无效;请改为提供 ttl 或 expire_time。
在Databricks CLI版本0.287.0中添加
parent String 将在其中创建此分支的项目。 格式:projects/{project_id}
在Databricks CLI版本0.287.0中添加
purge_on_delete 布尔 是否在分支数据被删除时清除。
在Databricks CLI版本1.7.0中添加
replace_existing 布尔 是否替换部署时具有相同 ID 的现有分支。
在Databricks CLI版本1.0.0中添加的
source_branch String 从中创建此分支的源分支的名称(用于时间点恢复的数据世系)。 如果未指定,则默认为项目的默认分支。 格式:projects/{project_id}/branches/{branch_id}
在Databricks CLI版本0.287.0中添加
source_branch_lsn String 从中创建此分支的源分支上的日志序列号(LSN)。
在Databricks CLI版本0.287.0中添加
source_branch_time String 创建此分支的源分支上的时间点。
在Databricks CLI版本0.287.0中添加
source_snapshot String 该分支创建的快照。 设置时,分支的数据来自快照而非源分支,因此 source_branch、 source_branch_lsn和 source_branch_time 必须为空。 快照必须属于 AVAILABLE 该分支的项目。 格式:projects/{project_id}/snapshots/{snapshot_id}
在Databricks CLI版本1.16.0中添加
ttl String 相对生存时间持续时间。 设置后,分支将在 creation_time + ttl 过期。
在Databricks CLI版本0.287.0中添加

Example

请参阅 postgres_projects示例。

postgres_catalog

重要

此功能在 Beta 版中。

Type: Map

Postgres 目录资源允许在捆绑包中定义 Lakebase Postgres 目录 。 每个目录将 Unity 目录绑定到 Lakebase 自动缩放分支上的 Postgres 数据库。

在Databricks CLI版本1.0.0中添加的

postgres_catalogs:
  <postgres_catalog-name>:
    <postgres_catalog-field-name>: <postgres_catalog-field-value>
Key 类型 Description
branch String 支持目录的 Lakebase 自动缩放分支。
在Databricks CLI版本1.0.0中添加的
catalog_id String 必填。 要绑定到 Postgres 数据库的 Unity 目录目录的 ID。
在Databricks CLI版本1.0.0中添加的
create_database_if_missing 布尔 如果 Postgres 数据库尚不存在,则是否创建该数据库。
在Databricks CLI版本1.0.0中添加的
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.0.0中添加的
postgres_database String 必填。 要绑定到目录的 Postgres 数据库的名称。
在Databricks CLI版本1.0.0中添加的

Example

resources:
  postgres_projects:
    project:
      project_id: test-pg-project
      display_name: Test Postgres Project

  postgres_catalogs:
    catalog:
      catalog_id: test_catalog
      branch: ${resources.postgres_projects.project.name}/branches/production
      postgres_database: appdb
      create_database_if_missing: true

postgres_database

重要

此功能在 Beta 版中。

Type: Map

Postgres 数据库资源允许在捆绑包中定义 Lakebase Postgres 数据库 。 每个数据库在 Lakebase 自动缩放分支上创建。

在Databricks CLI版本1.4.0中添加

postgres_databases:
  <postgres_database-name>:
    <postgres_database-field-name>: <postgres_database-field-value>
Key 类型 Description
database_id String 必填。 要用于数据库的 ID。 这将成为数据库资源名称的最终组件。
在Databricks CLI版本1.4.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.4.0中添加
parent String 必填。 创建此数据库的分支。 格式: projects/{project_id}/branches/{branch_id}.
在Databricks CLI版本1.4.0中添加
postgres_database String Postgres 数据库的名称。
在Databricks CLI版本1.4.0中添加
replace_existing 布尔 是否替换部署时具有相同 ID 的现有数据库。
在Databricks CLI版本1.7.0中添加
role String 创建时必需。 拥有数据库的 Postgres 角色的资源名称。 格式: projects/{project_id}/branches/{branch_id}/roles/{role_id}.
在Databricks CLI版本1.4.0中添加

Examples

resources:
  postgres_projects:
    my_project:
      project_id: test-pg-proj
      display_name: 'Test Project for Database'
      pg_version: 16
      history_retention_duration: '604800s'

  postgres_branches:
    main:
      parent: ${resources.postgres_projects.my_project.id}
      branch_id: main
      no_expiry: true

  postgres_roles:
    owner:
      parent: ${resources.postgres_branches.main.id}
      role_id: app-owner
      postgres_role: app_owner

  postgres_databases:
    my_database:
      parent: ${resources.postgres_branches.main.id}
      database_id: my-database
      postgres_database: app_db
      # The live API requires `role`. Declare an explicit role so the bundle is
      # portable across users (the auto-created project-owner role's id is
      # derived from the creator's identity).
      role: ${resources.postgres_roles.owner.id}

postgres_endpoint

重要

此功能在 Beta 版中。

Type: Map

Postgres 端点资源允许你在捆绑包中定义 Lakebase 计算端点 。 还必须定义相应的 Lakebase 项目 和 Lakebase 分支。

在Databricks CLI版本0.287.0中添加

postgres_endpoints:
  <postgres_endpoint-name>:
    <postgres_endpoint-field-name>: <postgres_endpoint-field-value>
Key 类型 Description
autoscaling_limit_max_cu 编号 最大计算单位数。 最小值为 0.5。
在Databricks CLI版本0.287.0中添加
autoscaling_limit_min_cu 编号 最小计算单位数。 最小值为 0.5。
在Databricks CLI版本0.287.0中添加
disabled 布尔 是否限制与计算终结点的连接。 启用此选项将计划暂停计算作。 连接或控制台作无法启用禁用的计算终结点。
在Databricks CLI版本0.287.0中添加
endpoint_id String 要用于终结点的 ID。 这将成为终结点资源名称的最终组件。 ID 是必需的,并且长度必须为 1-63 个字符,以小写字母开头,并且仅包含小写字母、数字和连字符。 例如,primary 将变为 projects/my-app/branches/development/endpoints/primary。
在Databricks CLI版本0.287.0中添加
endpoint_type String 终结点类型。 分支只能有一个READ_WRITE终结点。 可能的值: ENDPOINT_TYPE_READ_WRITE、 ENDPOINT_TYPE_READ_ONLY。
在Databricks CLI版本0.287.0中添加
group Map 终结点组配置。 请参阅 postgres_endpoint.group。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.287.0中添加
no_suspension 布尔 设置为 true 时,显式禁用自动挂起(永不挂起)。 在提供时应设置为 true。
在Databricks CLI版本0.287.0中添加
parent String 将在其中创建此终结点的分支。 格式:projects/{project_id}/branches/{branch_id}
在Databricks CLI版本0.287.0中添加
replace_existing 布尔 是否替换部署时具有相同 ID 的现有计算终结点。
在Databricks CLI版本1.0.0中添加的
settings Map 计算终结点的设置集合。
在Databricks CLI版本0.287.0中添加
suspend_timeout_duration String 处于非活动状态的持续时间,之后计算终结点会自动挂起。 如果指定应介于 60 到 604800 秒之间(1 分钟到 1 周)。
在Databricks CLI版本0.287.0中添加

postgres_endpoint.group

Type: Map

终结点组配置。

Key 类型 Description
enable_readable_secondaries 布尔 是否允许对读写终结点进行只读连接。 仅与读写终结点相关。其中 group.max > 1。
max Integer 必填。 终结点组中的最大计算数。 目前,这必须等于 min。 设置为 1 单个计算终结点,以禁用高可用性(HA)。 若要手动挂起终结点组中的所有计算,请在终结点上设置为disabledtrue。
min Integer 必填。 终结点组中的最小计算数。 目前,这必须等于 max。 这必须大于或等于 1。

Example

请参阅 postgres_projects示例。

postgres_project

重要

此功能在 Beta 版中。

Type: Map

Postgres 项目资源允许在捆绑包中定义 Lakebase 自动缩放 Postgres 数据库项目 。 还必须定义相应的 Postgres 分支 和 计算终结点。

在Databricks CLI版本0.287.0中添加

postgres_projects:
  <postgres_project-name>:
    <postgres_project-field-name>: <postgres_project-field-value>
Key 类型 Description
budget_policy_id String 此项目的预算策略 ID。
custom_tags Sequence 此项目的自定义标记。 请参阅 postgres_project.custom_tags。
default_branch String 项目的默认分支,采用格式 projects/{project_id}/branches/{branch_id}。
default_endpoint_settings Map 计算终结点的设置集合。 请参阅 postgres_project.default_endpoint_settings。
在Databricks CLI版本0.287.0中添加
display_name String 人工可读项目名称。 长度应介于 1 到 256 个字符之间。
在Databricks CLI版本0.287.0中添加
enable_pg_native_login 布尔 是否为项目启用本机 Postgres 登录。
在Databricks CLI版本0.294.0中添加
history_retention_duration String 保留此项目所有分支的时间点恢复的共享历史记录的秒数。 值应介于 0 到 2592000s 之间(最多 30 天)。
在Databricks CLI版本0.287.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.287.0中添加
permissions Sequence Postgres 项目的权限。 查看 权限。
在Databricks CLI版本0.292.0中添加
pg_version Integer 主要 Postgres 版本号。 支持的版本为 16 和 17。
在Databricks CLI版本0.287.0中添加
project_id String 要用于Project的 ID。 这将成为项目资源名称的最终组件。 ID 是必需的,并且长度必须为 1-63 个字符,以小写字母开头,并且仅包含小写字母、数字和连字符。 例如,my-app 将变为 projects/my-app。
在Databricks CLI版本0.287.0中添加
purge_on_delete 布尔 是否在删除项目时清除项目的数据。
在Databricks CLI版本1.2.0中添加

示例

resources:
  postgres_projects:
    my_db:
      project_id: test-prod-app
      display_name: 'Production Database'
      pg_version: 17

  postgres_branches:
    main:
      parent: ${resources.postgres_projects.my_db.id}
      branch_id: main
      is_protected: false
      no_expiry: true

  postgres_endpoints:
    primary:
      parent: ${resources.postgres_branches.main.id}
      endpoint_id: primary
      endpoint_type: ENDPOINT_TYPE_READ_WRITE
      autoscaling_limit_min_cu: 0.5
      autoscaling_limit_max_cu: 4

postgres_project.custom_tags

Type: Sequence

项目的自定义标记列表。

Key 类型 Description
key String 自定义标记的键。
value String 自定义标记的值。

postgres_project.default_endpoint_settings

Type: Map

Key 类型 Description
autoscaling_limit_max_cu 编号 最大计算单位数。 最小值为 0.5。
autoscaling_limit_min_cu 编号 最小计算单位数。 最小值为 0.5。
no_suspension 布尔 设置为 true 时,显式禁用自动挂起(永不挂起)。 在提供时应设置为 true。 与 suspend_timeout_duration 互斥。
pg_settings Map Postgres 设置的原始表示形式。
suspend_timeout_duration String 处于非活动状态的持续时间,之后计算终结点会自动挂起。 如果指定应介于 60 到 604800 秒之间(1 分钟到 1 周)。 与 no_suspension 互斥。

postgres_role

重要

此功能在 Beta 版中。

Type: Map

Postgres 角色资源允许在捆绑包中定义 Lakebase Postgres 角色 。 每个角色在 Lakebase 自动缩放分支上创建。

在Databricks CLI版本1.4.0中添加

postgres_roles:
  <postgres_role-name>:
    <postgres_role-field-name>: <postgres_role-field-value>
Key 类型 Description
attributes Map 要与角色关联的所需 API 公开的 Postgres 角色属性。 请参阅 postgres_role.attributes。
在Databricks CLI版本1.4.0中添加
auth_method String 连接到 Postgres 时如何对角色进行身份验证。 如果未指定,则会从中 identity_type派生有意义的身份验证方法。 有效值为 NO_LOGIN, PG_PASSWORD_SCRAM_SHA_256LAKEBASE_OAUTH_V1。
在Databricks CLI版本1.4.0中添加
identity_type String 此角色表示的 Databricks 托管标识的类型。 留空以创建不与 Databricks 标识关联的常规 Postgres 角色。 有效值为 USER, SERVICE_PRINCIPALGROUP。
在Databricks CLI版本1.4.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.4.0中添加
membership_roles Sequence 此角色所属的标准角色。
在Databricks CLI版本1.4.0中添加
parent String 必填。 在其中创建此角色的分支。 格式: projects/{project_id}/branches/{branch_id}.
在Databricks CLI版本1.4.0中添加
postgres_role String Postgres 角色的名称。 创建角色时是必需的。 若要创建受托管 Databricks 标识支持的 Postgres 角色, postgres_role 必须是以下项之一:
  • 用户电子邮件,适用于 .identity_typeUSER
  • 应用程序 ID,适用于 .identity_typeSERVICE_PRINCIPAL
  • 组名称,用于 identity_type .GROUP

在Databricks CLI版本1.4.0中添加
replace_existing 布尔 是否替换部署时具有相同 ID 的现有角色。
在Databricks CLI版本1.7.0中添加
role_id String 必填。 用户指定的角色 ID;成为角色的资源名称的最终组件。 必须为 4-63 个字符、小写字母、数字和连字符(RFC 1123)。
在Databricks CLI版本1.4.0中添加

postgres_role.属性

Type: Map

要与角色关联的所需 API 公开的 Postgres 角色属性。

在Databricks CLI版本1.4.0中添加

Key 类型 Description
bypassrls 布尔 角色是否绕过行级别安全性。
createdb 布尔 角色是否可以创建数据库。
createrole 布尔 角色是否可以创建、更改、删除、批注和更改其他角色的安全标签。

Examples

resources:
  postgres_projects:
    my_project:
      project_id: my-pg-proj
      display_name: 'Test Project for Role'
      pg_version: 16
      history_retention_duration: '604800s'

  postgres_branches:
    main:
      parent: ${resources.postgres_projects.my_project.id}
      branch_id: main
      no_expiry: true

  postgres_roles:
    my_role:
      parent: ${resources.postgres_branches.main.id}
      role_id: my-role
      postgres_role: app_role
      attributes:
        createdb: true

postgres_snapshot_schedule

重要

此功能在 Beta 版中。

Type: Map

Postgres 快照计划资源允许你为 Lakebase 自动缩放项目 的分支在捆绑包中定义自动快照计划。

Note

使用声明式自动化包来定义Postgres快照调度,只有在使用 直接部署引擎时才支持。

在Databricks CLI版本1.16.0中添加

postgres_snapshot_schedules:
  <postgres_snapshot_schedule-name>:
    <postgres_snapshot_schedule-field-name>: <postgres_snapshot_schedule-field-value>
Key 类型 Description
branch String 必填。 该分支的自动快照调度由该分支管理。 格式: projects/{project_id}/branches/{branch_id}.
在Databricks CLI版本1.16.0中添加
lifecycle Map 控制资源部署生命周期的设置,例如防止资源被销毁。 请参阅 生命周期。
在Databricks CLI版本1.16.0中添加
schedule Sequence 自动快照拍摄的节奏。 空集合会禁用自动快照。 当多个节奏同时发射时,会拍摄一个快照并保留它们最长的状态。 详见 postgres_snapshot_schedule.schedule。
在Databricks CLI版本1.16.0中添加

postgres_snapshot_schedule.日程表

Type: Sequence

自动快照拍摄的节奏。

在Databricks CLI版本1.16.0中添加

每个项指定一个快照节奏(daily_schedule, , weekly_schedule或 monthly_schedule)及其 retention:

Key 类型 Description
daily_schedule Map 每天拍一张快照。
在Databricks CLI版本1.16.0中添加
monthly_schedule Map 每月拍一张快照。
在Databricks CLI版本1.16.0中添加
retention String 必填。 该节奏的快照会被保存多久,才会被自动删除。 至少要等一小时。 在拍摄快照时应用;不追溯生效,因此更改只影响后续快照。
在Databricks CLI版本1.16.0中添加
weekly_schedule Map 每周拍一张快照。
在Databricks CLI版本1.16.0中添加

postgres_synced_table

重要

此功能在 Beta 版中。

Type: Map

Postgres 同步表资源允许在捆绑包中定义 Lakebase Postgres 同步表 。 每个同步表都会连续将 Unity 目录增量源表复制到 Lakebase 自动缩放实例上的 Postgres 表。

在Databricks CLI版本1.0.0中添加的

postgres_synced_tables:
  <postgres_synced_table-name>:
    <postgres_synced_table-field-name>: <postgres_synced_table-field-value>
Key 类型 Description
branch String 在其中创建同步表的 Lakebase 自动缩放分支。
在Databricks CLI版本1.0.0中添加的
create_database_objects_if_missing 布尔 如果同步表的逻辑数据库和架构资源尚不存在,则是否创建它们。
在Databricks CLI版本1.0.0中添加的
existing_pipeline_id String 现有管道的 ID。 如果已设置,则同步表将打包到引用的现有管道中。 这可以避免创建新的管道并允许共享现有计算。 在这种情况下,该同步表的 scheduling_policy 必须与现有管道的调度策略相匹配。 最多只能定义 existing_pipeline_id 和 new_pipeline_spec 中的一个。
在Databricks CLI版本1.0.0中添加的
extra_columns Sequence 需要添加到同步表中的额外PostgreSQL列,除了从源表复制的那些。
在Databricks CLI版本1.10.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.0.0中添加的
new_pipeline_spec Map 新管道的技术规范。 请参阅 postgres_synced_table.new_pipeline_spec。 最多只能定义 existing_pipeline_id 和 new_pipeline_spec 中的一个。
在Databricks CLI版本1.0.0中添加的
postgres_database String 同步表的目标 Postgres 数据库的名称。
在Databricks CLI版本1.0.0中添加的
primary_key_columns Sequence 构成主键的列名列表。
在Databricks CLI版本1.0.0中添加的
scheduling_policy String 计划已同步表的基础管道的策略。 有效值为 CONTINUOUS, TRIGGEREDSNAPSHOT。
在Databricks CLI版本1.0.0中添加的
source_table_full_name String 源表的全名格式为catalog.schema.table。
在Databricks CLI版本1.0.0中添加的
synced_table_id String 必填。 要用于同步表的 ID。
在Databricks CLI版本1.0.0中添加的
timeseries_key String 用于取消重复具有相同主键的行的时序键。
在Databricks CLI版本1.0.0中添加的
type_overrides Sequence 覆盖特定列的默认 Delta-to PostgreSQL 类型映射。 参见 postgres_synced_table.type_overrides。
在Databricks CLI 1.5.0版本中添加

postgres_synced_table.新管道规范

Type: Map

同步表使用的新管道的规范。

在Databricks CLI版本1.0.0中添加的

Key 类型 Description
budget_policy_id String 要在新创建的管道上设置的预算策略。
storage_catalog String 用于存储中间文件的管道的目录,例如检查点和事件日志。 这必须是用户有权创建 Delta 表的标准目录。
storage_schema String 用于存储中间文件的管道的架构,例如检查点和事件日志。 这需要在用户有权创建 Delta 表的标准目录中。

postgres_synced_table.type_overrides

Type: Sequence

覆盖单列默认的 Delta-to PostgreSQL 类型映射。

在Databricks CLI 1.5.0版本中添加

Key 类型 Description
column_name String 必填。 目标PostgreSQL类型的源列名称应被覆盖。
在Databricks CLI 1.5.0版本中添加
pg_type String 必填。 用于该列的 PostgreSQL 专用目标类型。 有效值为:PG_SPECIFIC_TYPE_VECTOR、PG_SPECIFIC_TYPE_HALFVEC 和 PG_SPECIFIC_TYPE_VARCHAR。
在Databricks CLI 1.5.0版本中添加
size Integer 目标类型的大小参数,适用于取1的类型,如向量维数或varchar长度。 当被选 pg_type 中者需要尺码时才需要。
在Databricks CLI 1.5.0版本中添加

Example

resources:
  schemas:
    pipeline_storage:
      name: test_pipeline_storage
      catalog_name: main
      comment: 'Pipeline storage for the synced-table test'

  postgres_projects:
    my_project:
      project_id: test-pg-proj
      display_name: 'Test Project for Synced Table'
      pg_version: 17

  postgres_catalogs:
    my_catalog:
      catalog_id: lakebase_test
      branch: ${resources.postgres_projects.my_project.id}/branches/production
      postgres_database: appdb
      create_database_if_missing: true

  postgres_synced_tables:
    my_table:
      synced_table_id: ${resources.postgres_catalogs.my_catalog.catalog_id}.public.trips_synced
      source_table_full_name: main.source_test.trips_source
      primary_key_columns: ['tpep_pickup_datetime']
      scheduling_policy: SNAPSHOT
      postgres_database: appdb
      branch: ${resources.postgres_projects.my_project.id}/branches/production
      create_database_objects_if_missing: true
      new_pipeline_spec:
        storage_catalog: ${resources.schemas.pipeline_storage.catalog_name}
        storage_schema: ${resources.schemas.pipeline_storage.name}

quality_monitor(Unity目录)

Type: Map

quality_monitor 资源允许定义 Unity Catalog 表监视器。 有关监视器的信息,请参阅 数据分析。

声明式自动化捆绑包的 Python 支持质量监控。 见 databricks.bundles.quality_monitors。

quality_monitors:
  <quality_monitor-name>:
    <quality_monitor-field-name>: <quality_monitor-field-value>
Key 类型 Description
assets_dir String 用于存储监视资产的目录(例如仪表板、指标表)。
baseline_table_name String 从中计算偏移指标的基线表的名称。 监视表中的列还应存在于基线表中。
custom_metrics Sequence 用于在受监视表上进行计算的自定义指标。 这些指标可以是聚合指标、派生指标(从已计算的聚合指标)或偏移指标(跨时间窗口比较指标)。 请参阅 custom_metrics。
inference_log Map 用于监控推理日志的配置。 请参阅 inference_log。
latest_monitor_failure_msg String 监视器失败的最新错误消息。 这是在监视器失败时填充的只读字段。
新增于 Databricks CLI 0.264.0 版本
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
notifications Map 监视器的通知设置。 请参阅 通知。
output_schema_name String 用于创建输出指标表的架构。
schedule Map 自动更新和刷新指标表的计划。 请参阅 计划。
skip_builtin_dashboard 布尔 是否跳过创建汇总数据质量指标的默认仪表板。
slicing_exprs Sequence 用于切片数据以进行目标分析的列表达式列表。 数据按每个表达式独立分组,从而为每个谓词及其补码生成单独的切片。 对于高基数列,只有按频率排列的前 100 个唯一值才会生成切片。
snapshot Map 用于监视快照表的配置。 请参阅 快照。
table_name String 表的全名。
新增于 Databricks CLI 0.235.0 版本
time_series Map 用于监视时序表的配置。 请参阅 time_series。
warehouse_id String 用于为创建仪表板指定仓库的可选参数。 如果未指定,将使用第一个正在运行的仓库。

quality_monitor.custom_metrics

Type: Sequence

自定义指标定义列表。

列表中的每一项都是一个CustomMetric:

Key 类型 Description
definition String 用于指定如何计算指标的 SQL 表达式的 Jinja 模板。 请参阅 创建指标定义。
input_columns Sequence 需计算指标的输入表中的列名列表。 可用于 :table 指示指标需要来自多个列的信息。
name String 输出表中指标的名称。
output_data_type String 自定义指标的输出类型。
type String 只能是CUSTOM_METRIC_TYPE_AGGREGATE, CUSTOM_METRIC_TYPE_DERIVED或CUSTOM_METRIC_TYPE_DRIFT中的一个。 CUSTOM_METRIC_TYPE_AGGREGATE和CUSTOM_METRIC_TYPE_DERIVED指标在单个表上计算,而CUSTOM_METRIC_TYPE_DRIFT用于比较基线表和输入表的指标,或用于比较两个连续时间窗口之间的指标。
  • CUSTOM_METRIC_TYPE_AGGREGATE:仅依赖于您表中的现有列
  • CUSTOM_METRIC_TYPE_DERIVED:依赖于以前计算的聚合指标
  • CUSTOM_METRIC_TYPE_DRIFT:取决于以前计算的聚合或导出指标

quality_monitor.推理日志

Type: Map

用于监控推理日志的配置。

Key 类型 Description
granularities Sequence 聚合推理日志时的时间粒度(例如 ["1 day"])。
model_id_col String 包含模型 ID 的列的名称。
prediction_col String 包含预测的列的名称。
timestamp_col String 包含时间戳的列的名称。
problem_type String ML 问题的类型。 有效值包括 PROBLEM_TYPE_CLASSIFICATION,PROBLEM_TYPE_REGRESSION.
label_col String 包含标签的列的名称(基本事实)。
prediction_proba_col String 包含预测概率的列的名称。

quality_monitor.通知

Type: Map

监视器的通知设置。

Key 类型 Description
on_failure Map 监视器失败时的通知设置。 请参阅 on_failure。
on_new_classification_tag_detected Map 检测到新的分类标记时通知设置。 请参阅 on_new_classification_tag_detected。

quality_monitor.notifications.on_failure

Type: Map

监视器失败时的通知设置。

Key 类型 Description
email_addresses Sequence 用于监控故障通知的邮件地址列表。

quality_monitor.notifications.on_new_classification_tag_detected

Type: Map

检测到新的分类标记时通知设置。

Key 类型 Description
email_addresses Sequence 检测到新分类标记时要通知的电子邮件地址列表。

quality_monitor.日程

Type: Map

自动更新和刷新指标表的日程安排。

Key 类型 Description
quartz_cron_expression String 使用 Quartz 语法的 Cron 表达式。 例如,0 0 8 * * ? 每天早上8:00运行。
timezone_id String 计划的时区(例如 UTC, America/Los_Angeles)。
pause_status String 计划是否暂停。 有效值: PAUSED, UNPAUSED。

quality_monitor.snapshot

Type: Map

用于监视快照表的配置。

quality_monitor.时间级数

用于监视时序表的配置。

Key 类型 Description
granularities Sequence 用于聚合时序数据的时间粒度(例如 ["30 minutes"])。
timestamp_col String 包含时间戳的列的名称。

Examples

以下示例为 InferenceLog、 TimeSeries 和 快照 配置文件类型定义质量监视器。

# InferenceLog profile type
resources:
  quality_monitors:
    my_quality_monitor:
      table_name: dev.mlops_schema.predictions
      output_schema_name: ${bundle.target}.mlops_schema
      assets_dir: /Workspace/Users/${workspace.current_user.userName}/databricks_lakehouse_monitoring
      inference_log:
        granularities: [1 day]
        model_id_col: model_id
        prediction_col: prediction
        label_col: price
        problem_type: PROBLEM_TYPE_REGRESSION
        timestamp_col: timestamp
      schedule:
        quartz_cron_expression: 0 0 8 * * ? # Run Every day at 8am
        timezone_id: UTC
# TimeSeries profile type
resources:
  quality_monitors:
    my_quality_monitor:
      table_name: dev.mlops_schema.predictions
      output_schema_name: ${bundle.target}.mlops_schema
      assets_dir: /Workspace/Users/${workspace.current_user.userName}/databricks_lakehouse_monitoring
      time_series:
        granularities: [30 minutes]
        timestamp_col: timestamp
      schedule:
        quartz_cron_expression: 0 0 8 * * ? # Run Every day at 8am
        timezone_id: UTC
# Snapshot profile type
resources:
  quality_monitors:
    my_quality_monitor:
      table_name: dev.mlops_schema.predictions
      output_schema_name: ${bundle.target}.mlops_schema
      assets_dir: /Workspace/Users/${workspace.current_user.userName}/databricks_lakehouse_monitoring
      snapshot: {}
      schedule:
        quartz_cron_expression: 0 0 8 * * ? # Run Every day at 8am
        timezone_id: UTC

以下示例基于监视配置质量监视器和相应的模型重新训练作业:

# Quality monitoring workflow
resources:
  quality_monitors:
    mlops_quality_monitor:
      table_name: ${bundle.target}.mlops_demo.predictions
      output_schema_name: ${bundle.target}.mlops_demo
      assets_dir: /Users/${workspace.current_user.userName}/databricks_lakehouse_monitoring
      inference_log:
        granularities: [1 hour]
        model_id_col: model_version
        prediction_col: prediction
        label_col: fare_amount
        problem_type: PROBLEM_TYPE_REGRESSION
        timestamp_col: inference_timestamp
      schedule:
        quartz_cron_expression: 57 0 14 * * ? # refresh monitoring metrics every day at 7 am PT
        timezone_id: UTC
  jobs:
    retraining_job:
      name: ${bundle.target}-mlops_demo-monitoring-retraining-job
      tasks:
        - task_key: monitored_metric_violation_check
          notebook_task:
            notebook_path: ../monitoring/notebooks/MonitoredMetricViolationCheck.py
            base_parameters:
              env: ${bundle.target}
              table_name_under_monitor: ${bundle.target}.mlops_demo.predictions
              metric_to_monitor: r2_score
              metric_violation_threshold: 0.7
              num_evaluation_windows: 24
              num_violation_windows: 5 # 5 out of the past 24 windows have metrics lower than threshold

        - task_key: is_metric_violated
          depends_on:
            - task_key: monitored_metric_violation_check
          condition_task:
            op: EQUAL_TO
            left: '{{tasks.monitored_metric_violation_check.values.is_metric_violated}}'
            right: 'true'

        - task_key: trigger_retraining
          depends_on:
            - task_key: is_metric_violated
              outcome: 'true'
          run_job_task:
            job_id: ${resources.jobs.model_training_job.id}

      schedule:
        quartz_cron_expression: '0 0 15 * * ?' # daily at 8 am PDT
        timezone_id: UTC

      # To get notifications, provide a list of emails to the on_failure argument.
      #
      #  email_notifications:
      #    on_failure:
      #      - someone@example.com

registered_model(Unity 目录)

Type: Map

使用 registered model 资源,可以在 Unity Catalog 中定义模型。 有关 Unity 目录 注册的模型的信息,请参阅 Unity 目录中的管理模型生命周期。

Python 支持声明式自动化捆绑包中注册模型。 请看 databricks.bundles.registered_models。

registered_models:
  <registered_model-name>:
    <registered_model-field-name>: <registered_model-field-value>
Key 类型 Description
aliases Sequence 与已注册的模型关联的别名列表。 请参阅 registered_model.aliases。
新增于 Databricks CLI 版本 0.273.0
catalog_name String 架构和已注册模型所在的目录的名称。
comment String 附加到已注册模型的注释。
created_at Integer 自 Unix 纪元以来注册的模型的创建时间戳(以毫秒为单位)。
新增于 Databricks CLI 版本 0.273.0
created_by String 创建已注册模型的用户的标识符。
新增于 Databricks CLI 版本 0.273.0
full_name String 已注册模型的三级(完全限定)名称。
新增于 Databricks CLI 版本 0.273.0
grants Sequence 与注册模型关联的授予。 请参阅 授予。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
metastore_id String 元存储的唯一标识符。
新增于 Databricks CLI 版本 0.273.0
name String 已注册模型的名称。
owner String 拥有已注册模型的用户的标识符。
新增于 Databricks CLI 版本 0.273.0
schema_name String 已注册模型所在的架构的名称。
storage_location String 存储模型版本数据文件的云存储位置。
updated_at String 自 Unix 纪元以来已注册模型的上次更新时间戳(以毫秒为单位)。
新增于 Databricks CLI 版本 0.273.0
updated_by String 上次更新已注册模型的用户的标识符。
新增于 Databricks CLI 版本 0.273.0

registered_model.别名

Type: Sequence

与已注册的模型关联的别名列表。

列表中的每个项都是一个 Alias:

Key 类型 Description
alias_name String 别名的名称,例如“champion”或“latest_stable”
catalog_name String 包含模型版本的目录的名称
id String 别名的唯一标识符
model_name String 模型版本的父注册模型的名称,相对于父架构
schema_name String 包含模型版本的架构的名称,相对于父目录
version_num Integer 此别名指向的模型版本的整数版本号。

Example

以下示例在 Unity Catalog 中定义了注册的模型:

resources:
  registered_models:
    model:
      name: my_model
      catalog_name: ${bundle.target}
      schema_name: mlops_schema
      comment: Registered model in Unity Catalog for ${bundle.target} deployment target
      grants:
        - privileges:
            - EXECUTE
          principal: account users

schema(Unity 目录)

Type: Map

架构资源类型允许您为工作流和管道中的表及其他资产定义 Unity Catalog 架构,这些工作流和管道是作为捆绑包的一部分创建的。 不同于其他资源类型,架构具有以下限制:

  • 构架资源的所有者始终是部署用户,不能更改。 如果在捆绑包中指定了 run_as,则架构上的操作将忽略它。
  • 只有相应的 Schemas 对象创建 API 所支持的字段可用于该架构资源。 例如, enable_predictive_optimization 不支持,因为它仅在 更新 API 上可用。

声明式自动化捆绑包的 Python 支持模式。 请参阅 databricks.bundles.schemas。

schemas:
  <schema-name>:
    <schema-field-name>: <schema-field-value>
Key 类型 Description
catalog_name String 父目录的名称。
comment String 用户提供的自由格式文本说明。
custom_max_retention_hours Integer 模式的最大保留时间(小时)是定制的。
在Databricks CLI 1.5.0版本中添加
grants Sequence 与架构关联的授予。 请参阅 授予。
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 相对于父目录的架构名称。
properties Map 附加到架构的键值属性的映射。
storage_root String 架构中托管表的存储根 URL。

Examples

以下示例定义了一个管道,其中包含资源密钥 my_pipeline ,该管道创建一个 Unity 目录架构,该架构将密钥 my_schema 作为目标。 此示例使用 替换。

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline
      libraries:
        - notebook:
            path: ../src/nb.ipynb
        - file:
            path: ../src/range.sql
      development: true
      catalog: ${resources.schemas.my_schema.catalog_name}
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema
      catalog_name: main
      comment: This schema was created by Declarative Automation Bundles.

声明性自动化捆绑包不支持顶级授权映射,因此,如果要为架构设置授权,请在映射中定义架构的 schemas 授予。 有关授予的详细信息,请参阅 “显示”、“授予”和“撤销权限”。

以下示例定义了一个附带权限的 Unity Catalog 架构模式:

resources:
  schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - SELECT
        - principal: my_team
          privileges:
            - MANAGE
      catalog_name: main

secret(Unity 目录)

Type: Map

秘密资源允许你定义存储在 Unity 目录中的秘密。 秘密是三级命名空间对象(catalog.schema.secret),用于安全存储敏感的凭证数据,如密码、令牌和密钥。

声明式自动化捆绑包的 Python 支持秘密。 参见 databricks.bundles.secrets。

Note

只有在使用 直接部署引擎时,才支持使用声明式自动化捆绑来定义秘密。

在Databricks CLI版本1.12.0中添加

secrets:
  <secret-name>:
    <secret-field-name>: <secret-field-value>
Key 类型 Description
catalog_name String 必填。 目录名称,即模式和秘密所在的目录。
在Databricks CLI版本1.12.0中添加
comment String 用户提供的自由文本描述。 字符必须在1到65536之间。
在Databricks CLI版本1.12.0中添加
expire_time String 用户提供密钥的有效期。 该字段表示何时不应再使用该秘密,并可能在界面中显示为警告。 它纯粹是信息性质,不会触发任何自动操作,也不影响秘密的生命周期。
在Databricks CLI版本1.12.0中添加
grants Sequence 申请该秘密的资助。 请参阅 授予。
在Databricks CLI版本1.12.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本1.12.0中添加
name String 必填。 秘密名称相对于其父模式。
在Databricks CLI版本1.12.0中添加
owner String 秘密的主人。 创建时默认使用创建原则。 可以更新以将秘密的所有权转移给另一个委托人。
在Databricks CLI版本1.12.0中添加
schema_name String 必填。 秘密所在的模式名称。
在Databricks CLI版本1.12.0中添加
value String 必填。 隐藏的数值。 该字段仅输入,不会在响应中返回——使用 effective_value 该字段(通过 GetSecret ,设 include_value 为 true)读取秘密值。 最大容量为60 KiB(加密前)。 接受的内容包括密码、令牌、密钥及其他敏感凭证数据。 字符必须在1到61440个之间。
在Databricks CLI版本1.12.0中添加

Examples

以下示例定义了一个 Unity 目录秘密,其值由部署时的 bundle 变量提供:

bundle:
  name: my-bundle

variables:
  my_secret_value:
    description: 'Secret value passed at deploy time'

resources:
  secrets:
    my_secret:
      catalog_name: main
      schema_name: default
      name: my_api_key
      value: ${var.my_secret_value}
      comment: 'API key for external service'

secret_scope

Type: Map

secret_scope资源允许在捆绑包中定义 机密范围 。 有关机密范围的信息,请参阅 机密管理。

Python 支持声明式自动化捆绑包的秘密作用域。 请参见 databricks.bundles.secret_scopes。

在Databricks CLI版本0.252.0中添加

secret_scopes:
  <secret_scope-name>:
    <secret_scope-field-name>: <secret_scope-field-value>
Key 类型 Description
backend_type String 创建该作用域时将使用的后端类型。 如果未指定,则默认为 DATABRICKS.
在Databricks CLI版本0.252.0中添加
keyvault_metadata Map 机密范围的元数据(如果 backend_type 为 AZURE_KEYVAULT)。 请参阅 keyvault_metadata。
在Databricks CLI版本0.252.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 用户请求的范围名称。 范围名称是唯一的。
在Databricks CLI版本0.252.0中添加
permissions Sequence 应适用于密钥范围的权限。 权限通过秘密作用域的ACL管理,因此每个group_name、、或user_name都转换为ACL中的一个service_principal_nameprincipal字段。 允许的水平为 READ、 WRITE和 MANAGE。 查看 权限。
在Databricks CLI版本0.252.0中添加

secret_scope.keyvault_metadata

Type: Map

Azure 密钥保管库支持的机密范围的元数据。

Key 类型 Description
resource_id String 密钥保管库的Azure资源 ID。
dns_name String Azure 密钥保管库的 DNS 名称。

Examples

以下示例定义使用密钥保管库后端的机密范围:

resources:
  secret_scopes:
    secret_scope_azure:
      name: test-secrets-azure-backend
      backend_type: 'AZURE_KEYVAULT'
      keyvault_metadata:
        resource_id: my_azure_keyvault_id
        dns_name: my_azure_keyvault_dns_name

以下示例使用机密范围和权限设置自定义 ACL:

resources:
  secret_scopes:
    my_secret_scope:
      name: my_secret_scope
      permissions:
        - user_name: admins
          level: WRITE
        - user_name: users
          level: READ

有关演示如何使用捆绑包中读取机密范围的任务定义机密范围和作业的示例捆绑包,请参阅 bundle 示例GitHub存储库。

sql_warehouse

Type: Map

SQL 仓库资源允许在捆绑包中定义 SQL 仓库 。 有关 SQL 仓库的信息,请参阅 Azure Databricks 上的 Data warehouseing。

声明式自动化捆绑包的 Python 支持SQL 仓库。 参见 databricks.bundles.sql_warehouses。

在Databricks CLI版本0.260.0中添加

sql_warehouses:
  <sql-warehouse-name>:
    <sql-warehouse-field-name>: <sql-warehouse-field-value>
Key 类型 Description
auto_stop_mins Integer SQL 仓库在被自动停止之前,必须处于空闲状态的时间量(例如,没有 RUNNING 查询)。 有效值为0,表示无自动停止,或大于或等于10(经典/专业)或1(无服务器)。 默认是120(经典/专业版)和10(无服务器)。
在Databricks CLI版本0.260.0中添加
channel Map 通道详细信息。 请参阅 频道。
在Databricks CLI版本0.260.0中添加
cluster_size String 为此仓库分配的群集的大小。 增加 Spark 群集的大小可让你对它运行更大的查询。 如果要增加并发查询数,请优化max_num_clusters。 有关支持的值,请参阅 cluster_size。
在Databricks CLI版本0.260.0中添加
creator_name String 创建仓库的用户的名称。
在Databricks CLI版本0.260.0中添加
enable_photon 布尔 仓库是否应使用 Photon 优化群集。 默认值为 false。
在Databricks CLI版本0.260.0中添加
enable_serverless_compute 布尔 仓库是否应使用无服务器计算。
在Databricks CLI版本0.260.0中添加
instance_profile_arn String Deprecated. 用于将 IAM 角色传递给群集的实例配置文件。
在Databricks CLI版本0.260.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
max_num_clusters Integer 自动缩放程序创建的最大群集数,用于处理并发查询。 值必须小于或等于 30 且大于或等于 min_num_clusters。 如果未设置,则默认为min_clusters。
在Databricks CLI版本0.260.0中添加
min_num_clusters Integer 将为此 SQL 仓库维护的可用群集的最小数量。 增加这可确保越来越多的群集始终运行,因此可能会减少新查询的冷启动时间。 这类似于资源管理器中保留核心与可吊销核心的比较。 值必须大于 0 且小于或等于 min(max_num_clusters,30)。 默认值为 1。
在Databricks CLI版本0.260.0中添加
name String 群集的逻辑名称。 该名称在组织内必须唯一且少于 100 个字符。
在Databricks CLI版本0.260.0中添加
permissions Sequence 要应用于仓库的权限。 查看 权限。
在Databricks CLI版本0.260.0中添加
spot_instance_policy String 是否使用现成实例。 有效值为 POLICY_UNSPECIFIED, COST_OPTIMIZEDRELIABILITY_OPTIMIZED。 默认值为 COST_OPTIMIZED。
在Databricks CLI版本0.260.0中添加
statement_timeout Integer 仓库的语句超时,秒数。 请参阅 语句超时。
在Databricks CLI版本1.21.0中添加
tags Map 仓库的一组自定义标记。 请参阅 sql_warehouse.tags。
在Databricks CLI版本0.260.0中添加
warehouse_type String 仓库类型。 有效值为:PRO、CLASSIC 和 REALTIME。 如果要使用无服务器计算,请将此字段设置为 PRO ,并将该字段 enable_serverless_compute 设置为 true。
在Databricks CLI版本0.260.0中添加

sql_warehouse.channel

Type: Map

SQL 仓库的通道配置。

Key 类型 Description
name String 通道的名称。 有效值包括 CHANNEL_NAME_CURRENT, CHANNEL_NAME_PREVIEW。 CHANNEL_NAME_CUSTOM
dbsql_version String 自定义通道的 DBSQL 版本。

sql_warehouse.标签

Type: Map

SQL 仓库的自定义标记。

Key 类型 Description
custom_tags Sequence 一组键值对,用于标识与此 SQL 仓库关联的所有资源(例如 AWS 实例和 EBS 卷)上的标记。 标记数必须小于 45。

Example

以下示例定义 SQL 仓库:

resources:
  sql_warehouses:
    my_sql_warehouse:
      name: my_sql_warehouse
      cluster_size: X-Large
      enable_serverless_compute: true
      max_num_clusters: 3
      min_num_clusters: 1
      auto_stop_mins: 60
      warehouse_type: PRO
      tags:
        custom_tags:
          - key: 'bizunit'
            value: 'commercial'
          - key: 'area'
            value: 'marketing'

synced_database_table

Type: Map

通过同步的数据库表资源,可以在捆绑包中定义 Lakebase 数据库表 。

对于新工作负载,Databricks 推荐使用该 postgres_synced_tables 资源。

声明式自动化捆绑包的 Python 支持同步数据库表。 参见 databricks.bundles.synced_database_tables。

有关同步的数据库表的信息,请参阅 Lakebase 预配。

在Databricks CLI版本0.266.0中添加

synced_database_tables:
  <synced_database_table-name>:
    <synced_database_table-field-name>: <synced_database_table-field-value>
Key 类型 Description
database_instance_name String 目标数据库实例的名称。 在标准目录中创建同步的数据库表时,这是必需的。 在注册目录中创建同步数据库表时,这是可选的;如果在此情况下指定,数据库实例名称必须与注册目录一致,否则请求将被拒绝。
在Databricks CLI版本0.266.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
logical_database_name String 此表的目标 Postgres 数据库对象(逻辑数据库)的名称。
在注册的 Postgres 目录中创建同步表时,目标 Postgres 数据库名称被推断为注册目录的名称。 如果在这种情况下指定了该字段,Postgres数据库名称必须与注册目录的名称一致,否则请求将被拒绝。
在标准目录中创建同步表时,必须有该字段,且指定该字段后可以针对任意的 Postgres 数据库进行定位。 注意,这对 中的create_database_objects_if_missing域有启示spec。
在Databricks CLI版本0.266.0中添加
name String 必填。 表格的全名,格式 catalog.schema.table为 .
在Databricks CLI版本0.266.0中添加
spec Map 数据库表规范。 请参阅 同步的数据库表规范。
在Databricks CLI版本0.266.0中添加

synced_database_table.spec

Type: Map

数据库表规范。

在Databricks CLI版本0.266.0中添加

Key 类型 Description
create_database_objects_if_missing 布尔 如果同步表的逻辑数据库和架构资源尚不存在,则是否创建它们。
existing_pipeline_id String 现有管道的 ID。 如果已设置,则同步表将打包到引用的现有管道中。 这可以避免创建新的管道并允许共享现有计算。 在这种情况下,该同步表的 scheduling_policy 必须与现有管道的调度策略相匹配。 最多只能定义 existing_pipeline_id 和 new_pipeline_spec 中的一个。
new_pipeline_spec Map 新管道的技术规范。 请参阅 new_pipeline_spec。 最多只能定义 existing_pipeline_id 和 new_pipeline_spec 中的一个。
primary_key_columns Sequence 构成主键的列名列表。
scheduling_policy String 用于同步的调度策略。 有效值包括 SNAPSHOT, CONTINUOUS。 TRIGGERED
source_table_full_name String 源表的全名格式为catalog.schema.table。
timeseries_key String 用于取消重复具有相同主键的行的时序键。

synced_database_table.spec.new_pipeline_spec

Type: Map

同步数据库表使用的新管道的规范。

Key 类型 Description
budget_policy_id String 要在新创建的管道上设置的预算策略的 ID。
storage_catalog String 用于存储中间文件的管道的目录,例如检查点和事件日志。 这必须是用户有权创建 Delta 表的标准目录。
storage_schema String 用于存储中间文件的管道的架构,例如检查点和事件日志。 这需要在用户有权创建 Delta 表的标准目录中。

Examples

以下示例在相应的 数据库目录中定义同步的数据库表:

resources:
  database_instances:
    my_instance:
      name: my-instance
      capacity: CU_1
  database_catalogs:
    my_catalog:
      database_instance_name: my-instance
      database_name: 'my_database'
      name: my_catalog
      create_database_if_not_exists: true
  synced_database_tables:
    my_synced_table:
      name: ${resources.database_catalogs.my_catalog.name}.${resources.database_catalogs.my_catalog.database_name}.my_destination_table
      database_instance_name: ${resources.database_catalogs.my_catalog.database_instance_name}
      logical_database_name: ${resources.database_catalogs.my_catalog.database_name}
      spec:
        source_table_full_name: 'my_source_table'
        scheduling_policy: SNAPSHOT
        primary_key_columns:
          - my_pk_column
        new_pipeline_spec:
          storage_catalog: 'my_delta_catalog'
          storage_schema: 'my_delta_schema'

以下示例定义标准目录中的同步数据库表:

resources:
  synced_database_tables:
    my_synced_table:
      name: 'my_standard_catalog.public.synced_table'
      # database_instance_name is required for synced tables created in standard catalogs.
      database_instance_name: 'my-database-instance'
      # logical_database_name is required for synced tables created in standard catalogs:
      logical_database_name: ${resources.database_catalogs.my_catalog.database_name}
      spec:
        source_table_full_name: 'source_catalog.schema.table'
        scheduling_policy: SNAPSHOT
        primary_key_columns:
          - my_pk_column
        create_database_objects_if_missing: true
        new_pipeline_spec:
          storage_catalog: 'my_delta_catalog'
          storage_schema: 'my_delta_schema'

此示例创建一个同步的数据库表并为其自定义管道计划。 它假定你已拥有:

  • 名为 my-database-instance 的数据库实例
  • 名为 my_standard_catalog 的标准目录
  • 名为 default 的标准目录中的模式
  • 以source_delta.schema.customer为主键,命名为c_custkey的源增量表
resources:
  synced_database_tables:
    my_synced_table:
      name: 'my_standard_catalog.default.my_synced_table'
      database_instance_name: 'my-database-instance'
      logical_database_name: 'test_db'
      spec:
        source_table_full_name: 'source_delta.schema.customer'
        scheduling_policy: SNAPSHOT
        primary_key_columns:
          - c_custkey
        create_database_objects_if_missing: true
        new_pipeline_spec:
          storage_catalog: 'source_delta'
          storage_schema: 'schema'

  jobs:
    sync_pipeline_schedule_job:
      name: sync_pipeline_schedule_job
      description: 'Job to schedule synced database table pipeline.'
      tasks:
        - task_key: synced-table-pipeline
          pipeline_task:
            pipeline_id: ${resources.synced_database_tables.my_synced_table.data_synchronization_status.pipeline_id}
      schedule:
        quartz_cron_expression: '0 0 0 * * ?'

vector_search_endpoint

Type: Map

vector_search_endpoint资源允许在捆绑包中定义 AI 搜索终结点 。 有关 AI 搜索的信息,请参阅 Databricks AI 搜索。

声明式自动化捆绑包的 Python 支持向量搜索端点。 请参见 databricks.bundles.vector_search_endpoints。

Note

仅当使用 直接部署引擎时,才支持使用声明性自动化捆绑包来定义矢量搜索终结点。

新增于 Databricks CLI 版本 0.298.0

vector_search_endpoints:
  <vector_search_endpoint-name>:
    <vector_search_endpoint-field-name>: <vector_search_endpoint-field-value>
Key 类型 Description
budget_policy_id String 要用于此终结点的预算策略的 ID。
新增于 Databricks CLI 版本 0.298.0
endpoint_type String 终结点的类型。 有效值为 STORAGE_OPTIMIZED 和 STANDARD。
新增于 Databricks CLI 版本 0.298.0
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
新增于 Databricks CLI 版本 0.298.0
name String AI 搜索终结点的名称。
新增于 Databricks CLI 版本 0.298.0
permissions Sequence 要应用于 AI 搜索终结点的权限。 允许的水平为 CAN_CREATE、 CAN_MANAGE和 CAN_USE。 查看 权限。
新增于 Databricks CLI 版本 0.298.0
target_qps Integer AI 搜索终结点的目标查询每秒数。 与 num_replicas 互斥。 实际的副本计数是在索引创建或同步时基于该值计算的。 这是一个尽力而为的目标;系统并不保证能实现这一QPS。
在Databricks CLI版本0.299.2中添加

Example

以下示例定义 AI 搜索终结点:

# databricks.yml
bundle:
  name: vector-search-example
  engine: direct # Vector Search requires the direct deployment engine

resources:
  vector_search_endpoints:
    my_vector_search_endpoint:
      name: my_vector_search_endpoint
      endpoint_type: STANDARD

vector_search_index

Type: Map

vector_search_index资源允许在捆绑包中定义 矢量搜索索引 。 有关矢量搜索的信息,请参阅 Databricks AI 搜索。

声明式自动化捆绑包的 Python 支持向量搜索索引。 看 databricks.bundles.vector_search_indexes。

新增于 Databricks CLI 1.1.0 版本

vector_search_indexes:
  <vector_search_index-name>:
    <vector_search_index-field-name>: <vector_search_index-field-value>
Key 类型 Description
delta_sync_index_spec Map 增量同步索引的规范。 如果 index_type 为 DELTA_SYNC,则是必需的。 请参阅 vector_search_index.delta_sync_index_spec。
新增于 Databricks CLI 1.1.0 版本
direct_access_index_spec Map 直接矢量访问索引的规范。 如果 index_type 为 DIRECT_ACCESS,则是必需的。 请参阅 vector_search_index.direct_access_index_spec。
新增于 Databricks CLI 1.1.0 版本
endpoint_name String 必填。 要用于提供索引的终结点的名称。
新增于 Databricks CLI 1.1.0 版本
grants Sequence 与矢量搜索索引关联的授予。 请参阅 授予。
新增于 Databricks CLI 1.1.0 版本
index_subtype String (Beta)索引的子类型。 有效值为 HYBRID 和 FULL_TEXT。 VECTOR 不支持。
新增于 Databricks CLI 1.1.0 版本
index_type String 必填。 索引的类型。 有效值为:
  • DELTA_SYNC: 一个索引,自动与源 Delta 表同步,随着底层数据的变化自动且增量地更新索引。
  • DIRECT_ACCESS: 一个支持通过 REST 和 SDK API 直接读写向量和元数据的索引。 使用此模型,用户管理索引更新。 新增于 Databricks CLI 1.1.0 版本
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
新增于 Databricks CLI 1.1.0 版本
name String 必填。 索引的名称。
新增于 Databricks CLI 1.1.0 版本
primary_key String 必填。 索引的主键。
新增于 Databricks CLI 1.1.0 版本

vector_search_index.delta_sync_index_spec

Type: Map

增量同步索引的规范。

新增于 Databricks CLI 1.1.0 版本

Key 类型 Description
columns_to_index Sequence 可选。 columns_to_sync 的别名。 选择要包含在矢量索引中的列。 如果此字段为空,则包含源表中的所有列。 始终包括主键列和嵌入源列或嵌入向量列。 只能指定或指定其中一个columns_to_synccolumns_to_index。
columns_to_sync Sequence 可选。 选择要与矢量索引同步的列。 如果此字段为空,则源表中的所有列都与索引同步。 主键列和嵌入源列或嵌入向量列始终同步。
embedding_source_columns Sequence 包含嵌入源的列。
embedding_vector_columns Sequence 包含嵌入向量的列。
embedding_writeback_table String 可选。 要同步矢量索引内容和计算嵌入到的 Delta 表的名称。
pipeline_type String 管道执行模式。 有效值为:
  • TRIGGERED:系统在成功刷新流水线中的源表一次后停止处理,确保表基于更新开始时可用的数据进行更新。
  • CONTINUOUS:流水线会处理新数据进入源表时,以保持向量索引的新鲜。
source_table String 源表的名称。

vector_search_index.直接访问索引规范

Type: Map

直接向量访问索引的规范。

新增于 Databricks CLI 1.1.0 版本

Key 类型 Description
embedding_source_columns Sequence 包含嵌入源的列。 格式应为 array[double]。
embedding_vector_columns Sequence 包含嵌入向量的列。 格式应为 array[double]。
schema_json String 采用 JSON 格式的索引架构。 支持的类型包括integer:、long、、float、doubleboolean、string、date。 timestamp 矢量列支持的类型: array<float>, array<double>。

Example

以下示例定义 Delta Sync 矢量搜索索引:

resources:
  vector_search_endpoints:
    my_endpoint:
      name: my-endpoint
      endpoint_type: STANDARD
  vector_search_indexes:
    my_index:
      name: main.default.my_index
      endpoint_name: ${resources.vector_search_endpoints.my_endpoint.name}
      primary_key: id
      index_type: DELTA_SYNC
      delta_sync_index_spec:
        source_table: main.default.source
        pipeline_type: TRIGGERED
      grants:
        - principal: data-engineers
          privileges: [SELECT]

卷(Unity目录)

Type: Map

使用 volume 资源类型,可以将 Unity Catalog 卷作为捆绑包的一部分进行定义和创建。 在部署定义了卷的捆绑包时,请注意:

  • 在工作区中存在卷之后,才能在捆绑包的 artifact_path 中引用卷。 因此,如果要使用声明性自动化捆绑包创建卷,必须先在捆绑包中定义卷,将其部署到创建卷,然后在后续部署中 artifact_path 引用该卷。
  • 部署目标配置了 dev_${workspace.current_user.short_name} 后,捆绑包中的卷不会追加 mode: development 前缀。 但是,可以手动配置此前缀。 请参阅 自定义预设。

声明式自动化捆绑包的 Python 支持卷。 请参阅 databricks.bundles.volumes。

在Databricks CLI版本0.236.0中添加

volumes:
  <volume-name>:
    <volume-field-name>: <volume-field-value>
Key 类型 Description
catalog_name String 架构和卷的目录的名称。
在Databricks CLI版本0.236.0中添加
comment String 附加到卷的注释。
在Databricks CLI版本0.236.0中添加
grants Sequence 与卷关联的授予。 请参阅 授予。
在Databricks CLI版本0.236.0中添加
lifecycle Map 包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。 请参阅 生命周期。
在Databricks CLI版本0.268.0中添加
name String 卷的名称。
在Databricks CLI版本0.236.0中添加
schema_name String 卷所在的架构的名称。
在Databricks CLI版本0.236.0中添加
storage_location String 云上的存储位置。
在Databricks CLI版本0.236.0中添加
volume_type String 卷类型,EXTERNAL 或 MANAGED。 外部卷位于指定的外部位置。 托管卷位于由父架构、父目录或元存储指定的默认位置。 请参阅 托管卷与外部卷。

Example

以下示例创建了具有键 my_volume_id 的 Unity Catalog 卷:

resources:
  volumes:
    my_volume_id:
      catalog_name: main
      name: my_volume
      schema_name: my_schema

有关运行写入 Unity 目录卷中的文件的作业的示例捆绑包,请参阅 bundle 示例GitHub存储库。

常见对象

格兰特

Type: Map

定义要授予该主体的主体和特权。 有关授予的详细信息,请参阅 “显示”、“授予”和“撤销权限”。

Key 类型 Description
principal String 将被授予特权的主体的名称。 可以是用户、组或服务主体。
privileges Sequence 给指定实体授予的权限。 有效值取决于资源类型(例如,SELECT、、MODIFY、CREATE、USAGE、READ_FILESWRITE_FILES、、EXECUTE、 )。 ALL_PRIVILEGES

Example

以下示例定义了一个附带权限的 Unity Catalog 架构模式:

resources:
  schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - SELECT
        - principal: my_team
          privileges:
            - MANAGE
      catalog_name: main

生命周期

Type: Map

包含资源的生命周期设置。 它在部署或销毁资源时控制资源的行为。

在Databricks CLI版本0.268.0中添加

Key 类型 Description
depends_on Sequence 这些资源必须在该资源之前部署,之后删除。 每个项目都有一个必备 resource 的键,指定要依赖的资源键,如 foojobs.foo或 。 与变量引用不同,这只影响排序。
在Databricks CLI版本1.23.0中添加
prevent_destroy 布尔 用于防止资源被销毁的生命周期设置。
在Databricks CLI版本0.268.0中添加
started 布尔 生命周期设置,用于在启动模式下部署资源。 仅在 直接部署模式下支持应用、群集和sql_warehouses。
在Databricks CLI版本0.297.0 (应用)中添加
在Databricks CLI版本1.1.0(集群)中添加 的
新增于 Databricks CLI 1.2.0 版本 (sql_warehouses)
triggers Sequence 这些条件会重新触发运行,同时配置也会变更。 仅支持 job_run.
在Databricks CLI版本1.13.0中添加