Databricks 小工具

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

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

Databricks 小工具最適合：

• 建立可用不同參數重新執行的筆記本或儀錶板。
• 快速探索具有不同參數的單一查詢結果。

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

Databricks 小工具類型

有 4 種類型的小工具：

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

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

建立 Widget

本節說明如何透過 UI 建立小工具，或使用 SQL 技巧或適用於 Python、Scala 和 R 的小工具 API，以程式化方式建立小工具。

透過 UI 建立小工具

使用筆記本 UI 建立小工具。 如果您已連線到 SQL 倉儲，這是您建立小工具的唯一方式。 選取 [編輯 > 新增參數]。

若要編輯 小工具設定，請按下齒輪圖示。

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

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

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

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

小工具 API 的設計目的是在 Scala、Python 和 R 中保持一致。SQL 中的小工具 API 稍有不同，但相當於其他語言。 您可以透過 Databricks Utilities （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",  list("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 倉儲中使用元件值

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

Databricks Runtime 15.2 和更高版本提供 widgets 的參數標記功能。 舊版 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
   

小工具設定

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

1. 按一下小工具面板右端的 圖示。

2. 在快顯小工具面板設定對話框中，選擇小工具的運作方式。

   

   • 執行筆記本：每次選取新的值時，就會重新執行整個筆記本。
   • 運行已存取的命令：每次選擇新的值時，只會重新執行只提取該特定小工具值的儲存格。 這是建立小工具時的預設設定。 此組態中不會重新執行 SQL 儲存格。
   • 不執行任何動作：每次選取新的值時，不會重新執行任何動作。

3. 若要將小工具釘選到筆記本頂端，或將小工具放在第一個儲存格上方，請按一下 。 設定會依照每個使用者個別儲存。 再次按下指紋圖示，以重設為預設行為。

4. 如果您有筆記本的 CAN MANAGE 權限，您可以點擊 來配置小工具佈局。 您可以自訂每個小工具的順序和大小。 若要儲存或關閉變更，請按一下 。

   小工具佈局會與筆記本一起儲存。 如果您從預設組態變更小工具配置，則不會依字母順序新增小工具。

5. 若要將小工具設定重設為預設順序和大小，請按下 齒輪圖示 開啟 [小工具面板 設定] 對話框，然後按兩下 [重設版面配置]。 removeAll() 命令不會重設小工具配置。

儀表板中的 Databricks 小工具

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

使用 Databricks 小工具搭配 %run

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

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

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

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

限制

如需了解更多關於Databricks 筆記本的已知限制的資訊，請參閱 (英文)。