Databricks 小组件

  • 项目

使用输入小组件，可将参数添加到笔记本和仪表板。 可从 Databricks UI 或使用小组件 API 添加小组件。 若要添加或编辑小组件，必须具有对笔记本的“可编辑”权限。

如果运行 Databricks Runtime 11.3 LTS 或更高版本，则还可在 Databricks 笔记本中使用 ipywidgets。

Databricks 小组件最适用于以下目的：

  • 构建可使用不同参数重新执行的笔记本或仪表板。
  • 使用不同参数快速浏览单个查询的结果。

若要查看有关 Scala、Python 和 R 中的小组件 API 的文档，请使用以下命令：dbutils.widgets.help()

Databricks 小组件类型

有 4 种类型的小组件：

  • text：在文本框中输入一个值。
  • dropdown：从提供的值列表中选择一个值。
  • combobox：文本和下拉列表的组合。 从提供的列表中选择一个值，或在文本框中输入一个值。
  • multiselect：从提供的值列表中选择一个或多个值。

小组件下拉列表和文本框会立即显示在笔记本工具栏后面。 小组件只接受字符串值。

Widget in header

使用 UI 创建小组件

若要创建小组件，请选择“编辑”>“添加小组件”。 在“添加小组件”对话框中，输入小组件名称、可选标签、类型、参数类型、可能的值和可选默认值。 在对话框中，“参数名称”是用于在代码中引用小组件的名称。 “小组件标签”是 UI 中小组件上显示的可选名称。

create widget dialog

创建小组件后，你可以将鼠标指针悬停在小组件名称上以显示描述如何引用小组件的工具提示。

widget tooltip

可使用短横线菜单编辑或删除小组件：

widget kebab menu

在计算群集上使用 Databricks 小组件

本部分介绍如何在附加到计算群集的笔记本中使用 Databricks 小组件。 若要在附加到 SQL 仓库的笔记本中使用小组件，请参阅在 SQL 仓库上使用 Databricks 小组件。

Databricks 小组件 API（群集）

小组件 API 设计为在 Scala、Python 和 R 中保持一致。SQL 中的小组件 API 略有不同，但等效于其他语言。 可通过 Databricks 实用程序 (dbutils) 参考界面来管理小组件。

  • 所有小组件类型的第一个参数是 name。 这是用于访问小组件的名称。
  • 第二个参数是 defaultValue；小组件的默认设置。
  • 第三个参数用于除 text 之外的所有小组件类型，它是 choices，即小组件可以采用的值列表。 此参数不用于 text 类型的小组件。
  • 最后一个参数是 label，它是显示在小组件文本框或下拉列表上的标签的可选值。

Databricks 小组件示例（群集）

若要查看每种方法的详细 API 文档，请使用 dbutils.widgets.help("<method-name>")。 帮助 API 在所有语言中都是相同的。 例如：

dbutils.widgets.help("dropdown")

创建一个简单的下拉小组件。

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

与小组件面板中的小组件进行交互。

Interact with widget

可通过调用访问小组件的当前值：

Python

dbutils.widgets.get("state")

SQL

SELECT "${state}"

最后，可删除笔记本中的某个小组件或所有小组件：

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

如果删除某个小组件，则无法在同一单元格中创建小组件。 必须在另一个单元格中创建小组件。

在 Spark SQL 中使用小组件值（群集）

Spark SQL 将小组件值作为可在查询中使用的字符串字面量进行访问。

在以交互方式执行笔记本时，可从 Spark SQL 访问用任何语言定义的小组件。 请考虑以下工作流：

  1. 创建当前目录中所有数据库的下拉小组件：

    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. 创建用于手动指定表名的文本小组件：

    dbutils.widgets.text("table", "")

  3. 运行 SQL 查询以查看数据库中的所有表（从下拉列表中选择）：

    SHOW TABLES IN ${database}

  4. 在 table 小组件中手动输入表名。

  5. 无需编辑查询内容即可预览表内容：

    SELECT *
FROM ${database}.${table}
LIMIT 100

注意

通常情况下，不能使用小组件在笔记本中的不同语言之间传递参数。 可在 Python 单元格中创建小组件 arg1 并在 SQL 或 Scala 单元格中使用它（如果逐个运行单元格）。 但是，如果使用“全部运行”或将笔记本作为作业运行，则无法做到这一点。

解决方法：

  • 对于未混合使用语言的笔记本，可为每种语言创建一个笔记本，并在运行笔记本时传递参数。
    • 可以使用 spark.sql() 调用来访问小组件。 例如，在 Python 中：spark.sql("select getArgument('arg1')").take(1)[0][0]。

注意

若要对 SQL 字符串字面量 中的 $ 字符进行转义，请使用 \$。 例如，若要表示字符串 $1,000，请使用 "\$1,000"。 无法为 SQL 标识符转义 $ 字符。

在 SQL 仓库上使用 Databricks 小组件

本部分介绍如何在附加到 SQL 仓库的笔记本中使用 Databricks 小组件。 若要在附加到计算群集的笔记本中使用小组件，请参阅在计算群集上使用 Databricks 小组件。

若要引用 SQL 仓库上的小组件值，请使用语法 :param，而不是 $param。 例如，如果有一个名为 fare_amount 的小组件，可使用类似于下面的代码：

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

使用 IDENTIFIER 关键字标识表、视图、架构和列等对象。 例如，如果名为 table_namesamples.nyctaxi.trips 的小组件设置为 ：

SELECT * FROM IDENTIFIER(:table_name)

有关详细信息，请参阅 IDENTIFIER 子句。

有关参数标记语法的详细信息，请参阅参数标记。

配置小组件设置

你可配置在选择新值时小组件的行为，配置小组件面板是否始终固定到笔记本顶部，并更改笔记本中小组件的布局。

  1. 单击“小组件”面板右端的gear icon图标。

  2. 在弹出式“小组件面板设置”对话框中，选择小组件的执行行为。

    Widget settings

    • 运行笔记本：每次选择新值时，整个笔记本都会重新运行。
    • 运行已访问的命令：每次选择新值时，只有检索该特定小组件值的单元格会重新运行。 这是创建小组件时的默认设置。 SQL 单元格不会在此配置中重新运行。
    • 不执行任何操作：每次选择新值时，任何内容都不会重新运行。

  3. 若要将小组件固定到笔记本顶部或将其放到第一个单元格上方，请单击pin icon。 设置按每位用户进行保存。 再次单击图钉图标可重置为默认行为。

  4. 如果有笔记本的“可管理”权限，则可单击 edit icon 来配置小组件布局。 可自定义每个小组件的顺序和大小。 若要保存或消除更改，请单击 accept and cancel icons。

    小组件布局随笔记本一起保存。 如果更改小组件布局，使其不使用默认配置，则不会按字母顺序添加新的小组件。

  5. 若要将小组件布局重置为默认顺序和大小，请单击gear icon来打开“小组件面板设置”对话框，然后单击“重置布局”。 removeAll() 命令不会重置小组件布局。

示例笔记本

可在以下笔记本中看到“运行已访问的命令”设置如何工作的演示。 year 小组件是使用 2014 设置创建的，用于数据帧 API 和 SQL 命令。

Widgets

将 year 小组件的设置更改为 2007 时，DataFrame 命令将重新运行，但 SQL 命令不会重新运行。

此笔记本演示了如何在附加到群集而不是 SQL 仓库的笔记本中使用小组件。

小组件演示笔记本

获取笔记本

仪表板中的 Databricks 小组件

从包含输入小组件的笔记本创建仪表板时，所有小组件都将显示在仪表板顶部。 在演示模式下，每次更新小组件的值时，都可单击“更新”按钮来重新运行笔记本并使用新值更新仪表板。

Dashboard with widgets

将 Databricks 小组件用于 %run

如果运行包含小组件的笔记本，指定的笔记本会使用该小组件的默认值运行。

如果笔记本附加到群集（即不是 SQL 仓库），则还可以将值传递到小组件。 例如：

%run /path/to/notebook $X="10" $Y="1"

此示例将运行指定的笔记本，并将 10 传递给小组件 X，将 1 传递给小组件 Y。

限制

  • 以下限制适用于小组件：
    • 一个笔记本中最多可以创建 512 个小组件。
    • 小组件名称限制为 1024 个字符。
    • 小组件标签限制为 2048 个字符。
    • 最多 2048 个字符可以输入到文本小组件。
    • 对于多选、组合框或下拉小组件，最多可以有 1024 个选项。
  • 存在一个已知问题，即在按“全部运行”后，即使在代码中清除或删除小组件，小组件状态也可能无法正确清除。 如果发生这种情况，你将看到小组件的视觉状态与其输出状态之间的差异。 单独重新运行单元格可能会绕过此问题。 若要完全避免此问题，Databricks 建议使用 ipywidgets。