Databricks 小工具

文章
05/17/2024

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

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

Databricks 小工具最適合：

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

若要在 Scala、Python 或 R 中檢視小工具 API 的檔，請使用下列命令： dbutils.widgets.help()

有 4 種類型的小工具：

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

小工具下拉式清單和文本框緊接在筆記本工具列之後。小工具只接受字串值。

建立 Widget

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

使用 UI 建立小工具

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

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

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

您可以使用 Kebab 選單來編輯或移除小工具：

使用 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", ["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() 子句，將字串剖析為資料庫、數據表、檢視表、函式、數據行和欄位等物件識別碼。
在 Widget 中手動輸入數據表名稱 table 。

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

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

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

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

本節說明如何將 Databricks 小工具值傳遞至 %sql Databricks Runtime 15.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"

使用 ${param} 語法傳入 Widget 值。

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

注意

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

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

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

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

範例筆記本

下列筆記本顯示執行 存取命令 設定的運作方式。小 year 工具會使用設定 2014 來建立，並用於DataFrame API和SQL命令。

當您將小工具的 year 設定變更為 2007時，DataFrame 命令會重新執行，但 SQL 命令不會重新執行。

此筆記本說明在連結至叢集的筆記本中使用小工具，而不是 SQL 倉儲。

取得筆記本

儀錶板中的 Databricks 小工具

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

搭配 %run 使用 Databricks 小工具

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

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

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

此範例會執行指定的筆記本，並傳遞至 Widget X，並1傳遞10至 Widget Y。

限制

下列限制適用於小工具：
- 最多可以在筆記本中建立 512 個小工具。
- 小工具名稱限制為1024個字元。
- 小工具標籤限製為 2048 個字元。
- 最多 2048 個字元可以輸入文字小工具。
- 多重選取、下拉式方塊或下拉式小工具最多可以有1024個選項。
有一個已知問題，即使清除或移除程序代碼中的小工具，在按下 [全部執行] 之後，小工具狀態可能無法正確清除。如果發生這種情況，您會看到小工具視覺效果與列印狀態之間的差異。個別重新執行儲存格可能會略過此問題。若要完全避免此問題，Databricks 建議使用 ipywidgets。

您不應該直接在異步內容中存取小工具狀態，例如線程、子進程或結構化串流（foreachBatch），因為小工具狀態在執行異步程式代碼時可能會變更。如果您需要存取異步內容中的小工具狀態，請以自變數的形式傳入。例如，如果您有下列使用線程的程序代碼：

import threading

def thread_func():
  # Unsafe access in a thread
  value = dbutils.widgets.get('my_widget')
  print(value)

thread = threading.Thread(target=thread_func)
thread.start()
thread.join()

然後您應該改為以這種方式撰寫：

# Access widget values outside the asynchronous context and pass them to the function
value = dbutils.widgets.get('my_widget')

def thread_func(val):
  # Use the passed value safely inside the thread
  print(val)

thread = threading.Thread(target=thread_func, args=(value,))
thread.start()
thread.join()

一般而言，小工具無法在筆記本內的不同語言之間傳遞自變數。如果您一次執行一個數據格，您可以在 Python 數據格中建立小工具 arg1 ，並在 SQL 或 Scala 數據格中使用它。不過，如果您使用 [全部 執行] 或執行筆記本做為作業，則無法運作。一些解決方法包括：
- 對於不混合語言的筆記本，您可以為每個語言建立筆記本，並在執行筆記本時傳遞自變數。
- 您可以使用呼叫來存取小工具 spark.sql() 。例如，在 Python 中： spark.sql("select getArgument('arg1')").take(1)[0][0]。

分享方式：

Databricks 小工具