Widget di Databricks

Articolo
12/27/2024

I widget di input consentono di aggiungere parameters ai notebook e ai dashboard. È possibile aggiungere un widget dall'interfaccia utente di Databricks o usando l'API del widget. Per aggiungere o modificare un widget, è necessario disporre delle autorizzazioni CAN EDIT per il notebook.

Se si esegue Databricks Runtime 11.3 LTS o versione successiva, è anche possibile usare ipywidgets nei notebook di Databricks.

I widget di Databricks sono ideali per:

Costruzione di un notebook o di un dashboard che viene rieseguito con diversi parameters.
Esplorazione rapida dei risultati di una singola query con diversi parameters.

Per visualizzare la documentazione per l'API del widget in Scala, Python o R, usare il comando seguente: dbutils.widgets.help(). È anche possibile fare riferimento alla documentazione dell'utilità widgets (dbutils.widgets).

Esistono 4 tipi di widget:

text: immettere un valore in una casella di testo.
dropdown: Select un valore proveniente da un list di valuesspecificato.
combobox: combinazione di testo ed elenco a discesa. Select un valore da un list fornito o inseriscine uno nella casella di testo.
multiselect: Select uno o più values da un list di valuesspecificato.

Gli elenchi a discesa dei widget e le caselle di testo vengono visualizzati immediatamente dopo la barra degli strumenti del notebook. I widget accettano solo stringhe values.

Creare widget

Questa sezione illustra come creare widget usando l'interfaccia utente o a livello di codice usando magic SQL o l'API widget per Python, Scala e R.

Creare widget usando l'interfaccia utente

Creare un widget usando l'interfaccia utente del notebook. Se si è connessi a un'istanza di SQL Warehouse, questo è l'unico modo per creare widget.

Select Modifica > Aggiungi widget. Nella finestra di dialogo Aggiungi widget, immettere il nome del widget, l'etichetta facoltativa, il tipo, il tipo di parametro, il possibile valuese il valore predefinito facoltativo. Nella finestra di dialogo, Nome parametro è il nome usato per fare riferimento al widget nel codice. L'Etichetta del widget è un nome facoltativo visualizzato sul widget nell'interfaccia utente.

Dopo aver creato un widget, è possibile passare il puntatore del mouse sul nome del widget per visualizzare un tooltip che descrive come fare riferimento al widget.

È possibile usare il menu kebab per modificare o remove il widget:

Creare widget con SQL, Python, R e Scala

Creare widget a livello di codice in un notebook collegato a un cluster di calcolo.

L'API widget è progettata per essere coerente in Scala, Python e R. L'API widget in SQL è leggermente diversa, ma equivalente alle altre lingue. È possibile gestire i widget tramite l'interfaccia di riferimento dbutils (Databricks Utilities).

Il primo argomento per tutti i tipi di widget è name. Questo è il nome usato per accedere al widget.
Il secondo argomento è defaultValue, l'impostazione predefinita del widget.
Il terzo argomento per tutti i tipi di widget (ad eccezione di text) è choices, un list di values il widget può assumere. Questo argomento non viene usato per i widget di tipo text.
L'ultimo argomento è label, un valore facoltativo per l'etichetta visualizzata nella casella di testo o nell'elenco a discesa del widget.

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

Interagire con il widget dal pannello del widget.

È possibile accedere al valore corrente del widget o get un mapping di tutti i widget:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Infine, puoi eseguire il comando remove su un widget o su tutti i widget in un notebook.

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

Se si remove un widget, non è possibile crearne uno nella stessa cella. È necessario creare il widget in un'altra cella.

Il widget di accesso a SPARK SQL e SQL Warehouse values usando marcatori di parametri . Gli indicatori di parametro proteggono il codice dagli attacchi SQL injection separando chiaramente le values fornite dalle istruzioni SQL.

I marcatori di parametro per i widget sono disponibili in Databricks Runtime 15.2 e versioni successive. Le versioni precedenti di Databricks Runtime devono usare la sintassi precedente per DBR 15.1 e versioni precedenti.

È possibile accedere ai widget definiti in qualsiasi linguaggio da Spark SQL durante l'esecuzione interattiva dei notebook. Si consideri il seguente flusso di lavoro:

Creare un widget a discesa di tutti i database nel catalogcorrente:

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

Creare un widget di testo per specificare manualmente un nome table:
```
dbutils.widgets.text("table", "")
```
Eseguire una query SQL per visualizzare tutti i tables in un database (selezionato dall'elenco a discesa list):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Nota

È necessario usare la clausola SQL IDENTIFIER() per analizzare le stringhe come identificatori di oggetto quali nomi per database, tables, views, funzioni, columnse campi .
Immettere manualmente un nome table nel widget table.
Creare un widget di testo per specificare un valore di filtro:
```
dbutils.widgets.text("filter_value", "")
```
Visualizzare in anteprima il contenuto di un table senza dover modificare il contenuto della query:
```
SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100
```

Questa sezione descrive come passare i widget di Databricks dalle values alle %sql celle del notebook in Databricks Runtime 15.1 e versioni precedenti.

Creare widget per specificare il testo 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"

Passa il widget values utilizzando la sintassi ${param}.

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

Nota

Per eseguire l'escape del carattere $ in un valore letterale stringa SQL, usare \$. Ad esempio, per esprimere la stringa $1,000, usare "\$1,000". Il carattere $ non può essere preceduto da un carattere di escape per gli identificatori SQL.

È possibile configurare il comportamento dei widget quando viene selezionato un nuovo valore, se il pannello del widget viene sempre aggiunto all'inizio del notebook, e modificare il layout dei widget nel notebook.

Fare clic sull'icona sul lato destro del pannello Widget.
Nella finestra di dialogo Impostazioni pannello del widget popup, scegliere il comportamento di esecuzione del widget.
- Esegui notebook: ogni volta che viene selezionato un nuovo valore, viene rieseguito l'intero notebook.
- Esegui comandi con accesso: ogni volta che viene selezionato un nuovo valore, vengono rieseguite solo le celle che recuperano il values per quel particolare widget. Questa è l'impostazione predefinita quando si crea un widget. Le celle SQL non vengono rieseguite in questa configurazione.
- Non eseguire alcuna operazione: ogni volta che viene selezionato un nuovo valore, non viene rieseguita alcuna operazione.
Per associare i widget nella parte superiore del notebook o per posizionare i widget sopra la prima cella, fare clic su . L'impostazione viene salvata per utente. Fare di nuovo clic sull'icona del cursore per reset al comportamento predefinito.
Se si dispone dell'autorizzazione CAN MANAGE per i notebook, è possibile configurare il layout del widget facendo clic su . È possibile personalizzare l'ordine e le dimensioni di ogni widget. Per salvare o eliminare le modifiche, fare clic su .

Il layout del widget viene salvato con il notebook. Se si modifica il layout del widget dalla configurazione predefinita, i nuovi widget non vengono aggiunti alfabeticamente.
Per reset il layout del widget su un ordine e dimensioni predefiniti, fare clic sull'icona a forma di ingranaggio per aprire la finestra di dialogo Impostazioni pannello widget e quindi fare clic su Reset Layout. Il comando removeAll() non reset il layout del widget.