Databricks 小组件

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

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

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

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

若要查看 Scala、Python 或 R 中小组件 API 的文档，请使用以下命令： dbutils.widgets.help() 还可以参考 小组件实用工具（dbutils.widgets）文档。

Databricks 小组件类型

有 4 种类型的小组件：

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

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

创建小组件

本部分介绍如何使用 UI 创建小组件，或使用 SQL magic 或 Python、Scala 和 R 的小组件 API 以编程方式创建小组件。

使用 UI 创建小组件

使用笔记本 UI 创建小组件。 如果连接到 SQL 仓库，这是创建小组件的唯一方法。

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

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

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

使用 SQL、Python、R 和 Scala 创建小组件

以编程方式在附加到计算群集的笔记本中创建小组件。

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

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

Python

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

Scala

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

R

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"))

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

可以访问小组件的当前值或获取所有小组件的映射：

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

在 Spark SQL 和 SQL Warehouse 中使用小组件值

Spark SQL 和 SQL Warehouse 使用参数标记访问小组件值。 参数标记通过清楚地将提供的值与 SQL 语句分开来保护代码免受 SQL 注入攻击。

Databricks Runtime 15.2 及更高版本中提供了小组件的参数标记。 之前版本的 Databricks Runtime 应使用 DBR 15.1 及更低版本的旧语法。

在以交互方式执行笔记本时，可从 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 IDENTIFIER(:database)
   

   注意

   必须使用 SQL IDENTIFIER() 子句将字符串分析为数据库、表、视图、函数、列和字段等对象标识符。

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

5. 创建文本小组件以指定筛选器值：

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

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

   SELECT *
   FROM IDENTIFIER(:database || '.' || :table)
   WHERE col == :filter_value
   LIMIT 100
   

在 Databricks Runtime 15.1 及更低版本中使用小组件值

本部分介绍如何将 Databricks 小组件值传递到 Databricks Runtime 15.1 及更低版本中的 %sql 笔记本单元格。

1. 创建小组件以指定文本值。

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

1. 使用 ${param} 语法传入小组件值。

   SELECT *
   FROM ${database}.${table}
   WHERE col == ${filter_value}
   LIMIT 100
   

注意

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

配置小组件设置

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

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

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

   

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

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

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

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

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

仪表板中的 Databricks 小组件

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

将 Databricks 小组件用于 %run

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

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

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

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

限制

有关详细信息，请参阅 Databricks 笔记本的已知限制。