Databricks-widgets

Artikel
12/03/2024

Met invoerwidgets kunt u parameters toevoegen aan uw notitieblokken en dashboards. U kunt een widget toevoegen vanuit de Databricks-gebruikersinterface of met behulp van de widget-API. Als u een widget wilt toevoegen of bewerken, moet u MACHTIGINGEN VOOR BEWERKEN voor het notitieblok hebben.

Als u Databricks Runtime 11.3 LTS of hoger uitvoert, kunt u ook ipywidgets gebruiken in Databricks-notebooks.

Databricks-widgets zijn het beste voor:

Een notebook of dashboard bouwen dat opnieuw wordt uitgevoerd met verschillende parameters.
Verken snel de resultaten van één query met verschillende parameters.

Gebruik de volgende opdracht om de documentatie voor de widget-API in Scala, Python of R weer te geven: dbutils.widgets.help() U kunt ook verwijzen naar de documentatie van het hulpprogramma widgets (dbutils.widgets).

Er zijn vier typen widgets:

text: Voer een waarde in een tekstvak in.
dropdown: Selecteer een waarde in een lijst met opgegeven waarden.
combobox: Combinatie van tekst en vervolgkeuzelijst. Selecteer een waarde in een opgegeven lijst of voer een in het tekstvak in.
multiselect: Selecteer een of meer waarden in een lijst met opgegeven waarden.

De vervolgkeuzelijsten en tekstvakken van de widget worden direct na de werkbalk van het notitieblok weergegeven. Widgets accepteren alleen tekenreekswaarden.

Widgets maken

In deze sectie wordt beschreven hoe u widgets maakt met behulp van de gebruikersinterface of programmatisch met behulp van SQL-magics of de widget-API voor Python, Scala en R.

Widgets maken met behulp van de gebruikersinterface

Maak een widget met behulp van de gebruikersinterface van het notitieblok. Als u bent verbonden met een SQL Warehouse, is dit de enige manier waarop u widgets kunt maken.

Selecteer >. Voer in het dialoogvenster Widget toevoegen de widgetnaam, optioneel label, type, parametertype, mogelijke waarden en optionele standaardwaarde in. In het dialoogvenster is Parameternaam de naam die u gebruikt om te verwijzen naar de widget in uw code. Widgetlabel is een optionele naam die wordt weergegeven via de widget in de gebruikersinterface.

Nadat u een widget hebt gemaakt, kunt u de widgetnaam aanwijzen om knopinfo weer te geven waarin wordt beschreven hoe u naar de widget verwijst.

U kunt het widgetmenu gebruiken om de widget te bewerken of te verwijderen:

Widgets maken met SQL, Python, R en Scala

Maak programmatisch widgets in een notebook dat is gekoppeld aan een rekencluster.

De widget-API is ontworpen om consistent te zijn in Scala, Python en R. De widget-API in SQL verschilt enigszins, maar komt overeen met de andere talen. U beheert widgets via de Databricks Utilities-referentieinterface (dbutils).

Het eerste argument voor alle widgettypen is name. Dit is de naam die u gebruikt voor toegang tot de widget.
Het tweede argument is defaultValue, de standaardinstelling van de widget.
Het derde argument voor alle widgettypen (behalve text) is choices, een lijst met waarden die de widget kan overnemen. Dit argument wordt niet gebruikt voor text type widgets.
Het laatste argument is label, een optionele waarde voor het label dat wordt weergegeven in het tekstvak of de vervolgkeuzelijst van de 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"))

Interactie met de widget vanuit het widgetvenster.

U kunt de huidige waarde van de widget openen of een toewijzing van alle widgets ophalen:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Ten slotte kunt u een widget of alle widgets in een notitieblok verwijderen:

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

Als u een widget verwijdert, kunt u er geen maken in dezelfde cel. U moet de widget maken in een andere cel.

Spark SQL- en SQL Warehouse-toegangswidgetwaarden met parametermarkeringen. Parametermarkeringen beschermen uw code tegen SQL-injectieaanvallen door opgegeven waarden duidelijk te scheiden van de SQL-instructies.

Parametermarkeringen voor widgets zijn beschikbaar in Databricks Runtime 15.2 en hoger. In eerdere versies van Databricks Runtime moet de oude syntaxis voor DBR 15.1 en lager worden gebruikt.

U hebt toegang tot widgets die zijn gedefinieerd in elke taal van Spark SQL tijdens het interactief uitvoeren van notebooks. Houd rekening met de volgende werkstroom:

Maak een vervolgkeuzelijstwidget van alle databases in de huidige catalogus:

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

Maak een tekstwidget om handmatig een tabelnaam op te geven:
```
dbutils.widgets.text("table", "")
```
Voer een SQL-query uit om alle tabellen in een database weer te geven (geselecteerd in de vervolgkeuzelijst):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Notitie

U moet de SQL-component IDENTIFIER() gebruiken om tekenreeksen te parseren als object-id's, zoals namen voor databases, tabellen, weergaven, functies, kolommen en velden.
Voer handmatig een tabelnaam in de table widget in.
Maak een tekstwidget om een filterwaarde op te geven:
```
dbutils.widgets.text("filter_value", "")
```
Bekijk een voorbeeld van de inhoud van een tabel zonder de inhoud van de query te hoeven bewerken:
```
SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100
```

In deze sectie wordt beschreven hoe u waarden voor Databricks-widgets doorgeeft aan %sql notebookcellen in Databricks Runtime 15.1 en hieronder.

Maak widgets om tekstwaarden op te geven.

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"

Geef de widgetwaarden door met behulp van de ${param} syntaxis.

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

Notitie

Als u het $ teken in een letterlijke SQL-tekenreeks wilt ontsnappen, gebruikt u \$. Als u bijvoorbeeld de tekenreeks $1,000wilt uitdrukken, gebruikt u "\$1,000". Het $ teken kan niet worden ontsnapt voor SQL-id's.

U kunt het gedrag van widgets configureren wanneer een nieuwe waarde is geselecteerd, of het widgetpaneel altijd aan de bovenkant van het notitieblok is vastgemaakt en de indeling van widgets in het notitieblok wijzigen.

Klik op het pictogram aan de rechterkant van het deelvenster Widget.
Kies in het dialoogvenster Instellingen voor het pop-upwidgetvenster de uitvoering van de widget.
- Notebook uitvoeren: telkens wanneer een nieuwe waarde wordt geselecteerd, wordt het hele notebook opnieuw uitgevoerd.
- Geopende opdrachten uitvoeren: telkens wanneer een nieuwe waarde wordt geselecteerd, worden alleen cellen die de waarden voor die specifieke widget ophalen, opnieuw uitgevoerd. Dit is de standaardinstelling wanneer u een widget maakt. SQL-cellen worden niet opnieuw uitgevoerd in deze configuratie.
- Niets doen: telkens wanneer een nieuwe waarde wordt geselecteerd, wordt er niets opnieuw uitgevoerd.
Als u de widgets aan de bovenkant van het notitieblok wilt vastmaken of de widgets boven de eerste cel wilt plaatsen, klikt u op . De instelling wordt per gebruiker opgeslagen. Klik nogmaals op het pictogram van de duimtack om het standaardgedrag opnieuw in te stellen.
Als u de machtiging CAN MANAGE voor notitieblokken hebt, kunt u de widgetindeling configureren door op te klikken. De volgorde en grootte van elke widget kunnen worden aangepast. Als u de wijzigingen wilt opslaan of sluiten, klikt u op .

De widgetindeling wordt opgeslagen met het notitieblok. Als u de indeling van de widget wijzigt in de standaardconfiguratie, worden nieuwe widgets niet alfabetisch toegevoegd.
Als u de indeling van de widget opnieuw wilt instellen op een standaardvolgorde en -grootte, klikt u om het dialoogvenster Instellingen voor het widgetvenster te openen en vervolgens op Indeling opnieuw instellen. Met removeAll() de opdracht wordt de widgetindeling niet opnieuw ingesteld.