Databricks 小工具

發行項
10/29/2024

輸入小工具可讓您將參數新增至筆記本和儀表板。您可以從 Databricks UI 或使用小工具 API 來新增小工具。若要新增或編輯小工具，您必須擁有筆記本的 CAN EDIT 權限。

如果您正在執行 Databricks Runtime 11.3 LTS 或更新版本，您也可以在 Databricks 筆記本中使用 ipywidgets。

Databricks 小工具最適合：

建置以不同參數重新執行的筆記本或儀表板。
快速探索具有不同參數的單一查詢結果。

若要在 Scala、Python 或 R 中檢視小工具 API 的檔，請使用下列命令： dbutils.widgets.help()。您也可以參考 Widgets 公用程式（dbutils.widgets）檔。

有 4 種類型的小工具：

text：在文字輸入框中輸入值。
dropdown：從提供的值清單中選取值。
combobox：文字和下拉式清單的組合。從提供的清單中選取值，或在文字輸入框中輸入值。
multiselect：從提供的值清單中選取一或多個值。

小工具下拉式清單和文字輸入框會在筆記本工具列之後立即顯示。小工具只接受字串值。

建立 Widget

本章節說明如何使用 UI 建立小工具，或使用 SQL magic 或 Python、Scala 和 R 的小工具 API，以程序設計方式建立小工具。

使用 UI 建立小工具

使用筆記本 UI 建立小工具。如果您已連線到 SQL 倉儲，這是您建立小工具的唯一方式。

選取 [編輯 > 新增小工具]。在 [新增小工具] 對話方塊中，輸入小工具名稱、選用的標籤、類型、參數類型、可能的值，以及選用的預設值。在對話方塊中，[參數名稱] 是您用來在程式碼中參考小工具的名稱。 [小工具標籤] 是 UI 中顯示在小工具上方的選用名稱。

建立小工具之後，您可以將滑鼠停留在小工具名稱上方，以顯示描述如何參考小工具的工具提示。

您可以使用 Kebab 功能表來編輯或移除小工具：

使用 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 倉儲會使用參數標記來存取小工具值。參數標記會清楚分隔提供的值與 SQL 陳述式，以保護您的程式碼免於遭受 SQL 插入式攻擊。

Databricks Runtime 15.2 和更新版本提供小工具的參數標記。舊版 Databricks Runtime 應該使用舊的 DBR 15.1 和以下版本的語法。

透過互動方式執行筆記本時，您可以從 Spark SQL 存取以任何語言定義的小工具。請考慮下列工作流程：

在目前目錄中建立所有資料庫的下拉式清單小工具：

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

建立文字小工具以手動指定資料表名稱：
```
dbutils.widgets.text("table", "")
```
執行 SQL 查詢以檢視資料庫中的所有資料表 (已從下拉式清單中選取)：
```
SHOW TABLES IN IDENTIFIER(:database)
```
注意

您必須使用 SQL IDENTIFIER() 子句，將字串剖析為資料庫、資料表、檢視、函數、資料行和欄位等物件識別碼。
在 table 小工具中手動輸入資料表名稱。

建立文字小工具以指定篩選值：

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

預覽資料表的內容，而不需要編輯查詢的內容：

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

本章節說明如何將 Databricks 小工具值傳遞至 Databricks Runtime 15.1 和以下版本中的 %sql 筆記本儲存格。

建立小工具以指定文字值。

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"

使用 ${param} 語法傳入小工具值。

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

注意

若要在 SQL 字串常值中逸出 $ 字元，請使用 \$。例如，若要表示字串 $1,000，請使用 "\$1,000"。 SQL 識別碼無法逸出 $ 字元。

您可以在選取新值時設定小工具的行為、小工具面板是否一律釘選到筆記本頂端，以及變更筆記本中小工具的配置。

按一下小工具面板右端的圖示。
在快顯的 [小工具面板設定] 對話框中，選擇小工具的執行行為。
- 執行筆記本：每次選取新的值時，就會重新執行整個筆記本。
- 執行存取的命令：每次選取新值時，只會重新執行擷取該特定小工具值的儲存格。這是建立小工具時的預設設定。此組態中不會重新執行 SQL 儲存格。
- 不執行任何動作：每次選取新的值時，不會重新執行任何動作。
若要將小工具釘選到筆記本頂端，或將小工具放在第一個儲存格上方，請按一下。設定會依照各個使用者來儲存。再次按一下圖釘圖示即可重設為預設行為。
如果您有筆記本的 CAN MANAGE 權限，您可以按一下來設定小工具配置。您可以自訂每個小工具的順序和大小。若要儲存或關閉變更，請按一下。

小工具配置會與筆記本一起儲存。如果您從預設組態變更小工具配置，則不會依字母順序新增小工具。
若要將小工具配置重設為預設順序和大小，請按一下以開啟 [小工具面板設定] 對話方塊，然後按一下 [重設配置]。 removeAll() 命令不會重設小工具配置。

儀表板中的 Databricks 小工具

從具有輸入小工具的筆記本建立儀表板時，所有小工具都會顯示在頂端。在簡報模式中，每次更新小工具的值時，您可以按一下 [更新] 按鈕以重新執行筆記本，並使用新的值更新儀表板。

使用 Databricks 小工具搭配 %run

您執行內含小工具的筆記本時，指定的筆記本會以小工具的預設值執行。

如果筆記本已連結至叢集 (而非 SQL 倉儲)，您也可以將值傳遞至小工具。例如：

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

此範例會執行指定的筆記本，並將 10 傳遞至小工具 X，且將 1 傳遞至小工具 Y。

限制

如需詳細資訊，請參閱已知限制 Databricks 筆記本 (英文)。

共用方式為

Databricks 小工具