Widget di Databricks

I widget di input consentono di aggiungere parametri 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:

• Creazione di un notebook o di un dashboard che viene eseguito di nuovo con parametri diversi.
• Esplorazione rapida dei risultati di una singola query con parametri diversi.

Per visualizzare la documentazione per l'API widget in Scala, Python o R, usare il comando seguente: dbutils.widgets.help()

Tipi di widget di Databricks

Esistono 4 tipi di widget:

• text: immettere un valore in una casella di testo.
• dropdown: selezionare un valore da un elenco di valori forniti.
• combobox: combinazione di testo e elenco a discesa. Selezionare un valore da un elenco specificato o immetterne uno nella casella di testo.
• multiselect: selezionare uno o più valori da un elenco di valori forniti.

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 valori stringa.

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.

Selezionare Modifica > aggiungi widget. Nella finestra di dialogo Aggiungi widget immettere il nome del widget, l'etichetta facoltativa, il tipo, il tipo di parametro, i valori possibili e 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 una descrizione comando che descrive come fare riferimento al widget.

È possibile usare il menu kebab per modificare o rimuovere 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 del 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 textdi ) è choices, un elenco di valori che il widget può assumere. Questo argomento non viene usato per text i widget di tipo.
• 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 ottenere 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, è possibile rimuovere un widget o 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 rimuove un widget, non è possibile crearne uno nella stessa cella. È necessario creare il widget in un'altra cella.

Usare i valori dei widget in Spark SQL e SQL Warehouse

Spark SQL e SQL Warehouse accedono ai valori dei widget usando marcatori di parametro. Gli indicatori di parametro proteggono il codice dagli attacchi SQL injection separando chiaramente i valori forniti 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 successive.

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

1. Creare un widget a discesa di tutti i database nel catalogo corrente:

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

2. Creare un widget di testo per specificare manualmente un nome di tabella:

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

3. Eseguire una query SQL per visualizzare tutte le tabelle in un database (selezionato dall'elenco a discesa):

   SHOW TABLES IN IDENTIFIER(:database)
   

   Nota

   È necessario usare la clausola SQL IDENTIFIER() per analizzare le stringhe come identificatori di oggetto come nomi di tali nomi per database, tabelle, viste, funzioni, colonne e campi.

4. Immettere manualmente un nome di tabella nel table widget.

5. Creare un widget di testo per specificare un valore di filtro:

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

6. Visualizzare in anteprima il contenuto di una tabella senza dover modificare il contenuto della query:

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

Usare i valori dei widget in Databricks Runtime 15.1 e versioni successive

Questa sezione descrive come passare i valori dei widget di Databricks alle %sql celle del notebook in Databricks Runtime 15.1 e versioni successive.

1. Creare widget per specificare i valori di testo.

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"

1. Passare i valori del widget usando la ${param} sintassi .

   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.

Configurare le impostazioni di widget

È 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.

1. Fare clic sull'icona alla fine destra del pannello Widget.

2. 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 i valori 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.

3. Per aggiungere i widget nella parte superiore del notebook o per posizionare i widget sopra la prima cella, fare clic su . L'impostazione viene salvata in base all'utente. Fare di nuovo clic sull'icona del cursore per ripristinare il comportamento predefinito.

4. 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 ignorare 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.

5. Per reimpostare il layout del widget su un ordine e dimensioni predefiniti, fare clic per aprire la finestra di dialogo Impostazioni pannello widget e quindi fare clic su Reimposta layout. Il removeAll() comando non reimposta il layout del widget.

Notebook di esempio

Il notebook seguente illustra il funzionamento dell'impostazione Esegui comandi accessibili. Il year widget viene creato con l'impostazione 2014 e viene usato nei comandi API DataFrame e SQL.

Quando si modifica l'impostazione del year widget su 2007, il comando DataFrame viene rieseguito, ma il comando SQL non viene rieseguito.

Questo notebook illustra l'uso di widget in un notebook collegato a un cluster, non a un data warehouse SQL.

Notebook dimostrativo del widget

Ottenere il notebook

Widget di Databricks nei dashboard

Quando si crea un dashboard da un notebook con widget di input, tutti i widget vengono visualizzati nella parte superiore. In modalità presentazione, ogni volta che si aggiorna il valore di un widget, è possibile fare clic sul pulsante Aggiorna per eseguire nuovamente il notebook e aggiornare il dashboard con nuovi valori.

Usare i widget di Databricks con %run

Se si esegue un notebook che contiene widget, il notebook specificato viene eseguito con i valori predefiniti del widget.

Se il notebook è collegato a un cluster (non a SQL Warehouse), è anche possibile passare valori ai widget. Ad esempio:

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

Questo esempio esegue il notebook specificato e passa 10 al widget X e 1 al widget Y.

Limiti

Per altre informazioni, vedere Limitazioni note dei notebook di Databricks.