Databricks-widgets

  • Artikel

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

Databricks-widgettypen

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.

Widget in koptekst

Widget maken met behulp van de gebruikersinterface

Als u een widget wilt maken, selecteert u De widget Toevoegen bewerken>. 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.

dialoogvenster widget maken

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

knopinfo voor widget

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

widget-menu voor widget

Databricks-widgets gebruiken in een rekencluster

In deze sectie wordt beschreven hoe u Databricks-widgets gebruikt in een notebook dat is gekoppeld aan een rekencluster. Als u widgets wilt gebruiken in een notebook die is gekoppeld aan een SQL-warehouse, raadpleegt u Databricks-widgets gebruiken in een SQL-warehouse.

Databricks widget-API (cluster)

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 is voor alle widgettypen, met uitzondering text van 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.

Voorbeeld van Databricks-widget (cluster)

Als u gedetailleerde API-documentatie voor elke methode wilt bekijken, gebruikt u dbutils.widgets.help("<method-name>"). De Help-API is identiek in alle talen. Voorbeeld:

dbutils.widgets.help("dropdown")

Maak een eenvoudige vervolgkeuzelijstwidget.

Python

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.

Interactie met widget

U kunt de huidige waarde van de widget openen met de aanroep:

Python

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

SQL

REMOVE WIDGET state

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

Widgetwaarden gebruiken in Spark SQL (cluster)

Spark SQL krijgt toegang tot widgetwaarden als letterlijke tekenreeksen die kunnen worden gebruikt in query's.

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:

  1. Maak een vervolgkeuzelijstwidget van alle databases in de huidige catalogus:

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

  2. Maak een tekstwidget om handmatig een tabelnaam op te geven:

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

  3. Voer een SQL-query uit om alle tabellen in een database weer te geven (geselecteerd in de vervolgkeuzelijst):

    SHOW TABLES IN ${database}

  4. Voer handmatig een tabelnaam in de table widget in.

  5. Bekijk een voorbeeld van de inhoud van een tabel zonder de inhoud van de query te hoeven bewerken:

    SELECT *
FROM ${database}.${table}
LIMIT 100

Notitie

Over het algemeen kunt u geen widgets gebruiken om argumenten door te geven tussen verschillende talen in een notitieblok. U kunt een widget arg1 maken in een Python-cel en deze gebruiken in een SQL- of Scala-cel als u één cel tegelijk uitvoert. Dit werkt echter niet als u Alles uitvoeren gebruikt of het notebook als taak uitvoert.

Tijdelijke oplossingen:

  • Voor notitieblokken die geen talen combineren, kunt u voor elke taal een notitieblok maken en de argumenten doorgeven wanneer u het notebook uitvoert.
    • U kunt de widget openen met behulp van een spark.sql() oproep. Bijvoorbeeld in Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

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.

Databricks-widgets gebruiken in een SQL Warehouse

In deze sectie wordt beschreven hoe u Databricks-widgets gebruikt in een notebook dat is gekoppeld aan een SQL Warehouse. Als u widgets wilt gebruiken in een notebook die is gekoppeld aan een rekencluster, raadpleegt u Databricks-widgets gebruiken in een rekencluster.

Als u wilt verwijzen naar widgetwaarden in een SQL Warehouse, gebruikt u de syntaxis :param, niet $param. Als u bijvoorbeeld een widget met de naam fare_amount hebt, gebruikt u code die lijkt op het volgende:

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

Gebruik het IDENTIFIER trefwoord om objecten zoals tabellen, weergaven, schema's en kolommen te identificeren. Als de widget met de naam table_name bijvoorbeeld is ingesteld op samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Zie de ID-component voor meer informatie.

Zie Parametermarkeringen voor meer informatie over de syntaxis van de parametermarkeringen.

Widgetinstellingen configureren

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.

  1. Klik op het tandwielpictogram pictogram aan de rechterkant van het deelvenster Widget.

  2. Kies in het pop-upwidgetvenster Instellingen dialoogvenster het uitvoeringsgedrag van de widget.

    Widgetinstellingen

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

  3. Als u de widgets aan de bovenkant van het notitieblok wilt vastmaken of de widgets boven de eerste cel wilt plaatsen, klikt u op speldpictogram. De instelling wordt per gebruiker opgeslagen. Klik nogmaals op het pictogram van de duimtack om het standaardgedrag opnieuw in te stellen.

  4. Als u de machtiging CAN MANAGE voor notitieblokken hebt, kunt u de widgetindeling configureren door op pictogram bewerkente klikken. De volgorde en grootte van elke widget kunnen worden aangepast. Als u de wijzigingen wilt opslaan of sluiten, klikt u op pictogrammen accepteren en annuleren.

    De widgetindeling wordt opgeslagen met het notitieblok. Als u de indeling van de widget wijzigt in de standaardconfiguratie, worden nieuwe widgets niet in alfabetische volgorde toegevoegd.

  5. Als u de widgetindeling opnieuw wilt instellen op een standaardvolgorde en -grootte, klikt u tandwielpictogram om het deelvenster Widget te openen Instellingen en klikt u vervolgens op Indeling opnieuw instellen. Met removeAll() de opdracht wordt de widgetindeling niet opnieuw ingesteld.

Voorbeeld van notebook

In het volgende notitieblok ziet u een demo over de werking van de instelling Opdrachten uitvoeren. De year widget wordt gemaakt met instelling 2014 en wordt gebruikt in DataFrame-API en SQL-opdrachten.

Widgets

Wanneer u de instelling van de year widget 2007wijzigt, wordt de DataFrame-opdracht opnieuw uitgevoerd, maar wordt de SQL-opdracht niet opnieuw uitgevoerd.

Dit notebook illustreert het gebruik van widgets in een notebook dat is gekoppeld aan een cluster, niet een SQL Warehouse.

Widgetdemonotitieblok

Notebook downloaden

Databricks-widgets in dashboards

Wanneer u een dashboard maakt op basis van een notitieblok met invoerwidgets, worden alle widgets boven aan het dashboard weergegeven. In de presentatiemodus kunt u telkens wanneer u de waarde van een widget bijwerkt op de knop Bijwerken klikken om het notitieblok opnieuw uit te voeren en uw dashboard bij te werken met nieuwe waarden.

Dashboard met widgets

Databricks-widgets gebruiken met %run

Als u een notebook met widgets uitvoert, wordt het opgegeven notebook uitgevoerd met de standaardwaarden van de widget.

Als het notebook is gekoppeld aan een cluster (dus geen SQL Warehouse), kunt u ook waarden doorgeven aan widgets. Voorbeeld:

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

In dit voorbeeld wordt het opgegeven notitieblok uitgevoerd en doorgegeven 10 aan widget X en 1 in widget Y.

Beperkingen

  • De volgende limieten gelden voor widgets:

    • Er kunnen maximaal 512 widgets worden gemaakt in een notitieblok.
    • Een widgetnaam is beperkt tot 1024 tekens.
    • Een widgetlabel is beperkt tot 2048 tekens.
    • Er kunnen maximaal 2048 tekens worden ingevoerd voor een tekstwidget.
    • Er kunnen maximaal 1024 opties zijn voor een meervoudige selectie, keuzelijst met invoervak of vervolgkeuzelijstwidget.

  • Er is een bekend probleem waarbij een widgetstatus mogelijk niet correct wist nadat u op Alles uitvoeren hebt gedrukt, zelfs na het wissen of verwijderen van de widget in code. Als dit gebeurt, ziet u een discrepantie tussen de visuele status van de widget en de afgedrukte status. Het opnieuw uitvoeren van de cellen kan dit probleem omzeilen. Om dit probleem volledig te voorkomen, raadt Databricks aan dat je ipywidgets gebruikt.

  • U moet de widgetstatus niet rechtstreeks openen in asynchrone contexten, zoals threads, subprocessen of Structured Streaming (foreachBatch), omdat de widgetstatus kan veranderen terwijl de asynchrone code wordt uitgevoerd. Als u toegang wilt krijgen tot de widgetstatus in asynchrone context, geeft u deze door als een argument. Als u bijvoorbeeld de volgende code hebt die threads gebruikt:

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

    Vervolgens moet u deze op deze manier schrijven:

    # 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()