Databricks 小工具

發行項
12/27/2024

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

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

Databricks 小工具最適合：

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

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

有 4 種類型的小工具：

text：在文字輸入框中輸入值。
dropdown：Select 是一個來自提供的 values的 list 的值。
combobox：文字和下拉式清單的組合。從提供的 list 中選擇 Select，或在文字框中輸入一個值。
multiselect：從提供的list中選擇一或多個values的Selectvalues。

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

建立 Widget

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

使用 UI 建立小工具

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

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

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

您可以使用 kebab 選單來編輯或 remove 小工具：

使用 SQL、Python、R 和 Scala 建立小工具

以程序設計方式在連結至計算叢集的筆記本中建立小工具。

小工具 API 的設計目的是在 Scala、Python 和 R 中保持一致。SQL 中的小工具 API 稍有不同，但相當於其他語言。您可以透過 Databricks 公用程式 (dbutils) 參考介面來管理小工具。

所有小工具類型的第一個引數是 name。這是您用來存取小工具的名稱。
第二個引數為 defaultValue，這是小工具的預設設定。
所有小工具類型的第三個自變數（text除外）是 choices，小工具可以接受 valueslist。這個引數不會用於 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"))

從小工具面板與小工具互動。

您可以存取小工具的目前值，或 get 所有小工具的映射關係。

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

最後，您可以在筆記本中 remove 一個小工具或所有小工具：

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

如果您 remove 一個控件，就無法在同一個儲存格中創建一個。您必須在另一個儲存格中建立小工具。

Spark SQL 和 SQL 倉儲存取小工具 values 使用參數標記。參數標記會藉由清楚地分隔提供的 values 與 SQL 語句，保護您的程式代碼免於遭受 SQL 插入式攻擊。

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

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

在當前的 catalog中建立一個包含所有資料庫的下拉式小工具：

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

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

您必須使用 SQL IDENTIFIER() 子句，將字串剖析為資料庫、tables、views、函式、columns和字段等名稱的物件標識碼。
在 table 小工具中手動輸入 table 名稱。

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

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

預覽 table 的內容，而不需要編輯查詢的內容：

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

本節說明如何將 Databricks 小工具 values 傳遞至 Databricks Runtime 15.1 或更低版本的 %sql 筆記本儲存格。

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

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} 語法傳入小工具 values。

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

注意

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

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

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

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

儀表板中的 Databricks 小工具

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

使用 Databricks 小工具搭配 %run

如果您執行包含小工具的筆記本，則會使用小工具的預設 values來執行指定的筆記本。

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

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

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

限制

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

共用方式為

Databricks 小工具