Databricks-widgetar

Artikel
03/10/2024

Med indatawidgetar kan du lägga till parametrar i dina notebook-filer och instrumentpaneler. Du kan lägga till en widget från Databricks-användargränssnittet eller använda widget-API:et. Om du vill lägga till eller redigera en widget måste du ha behörigheten KAN REDIGERA i notebook-filen.

Om du kör Databricks Runtime 11.3 LTS eller senare kan du också använda ipywidgets i Databricks Notebooks.

Databricks-widgetar passar bäst för:

Skapa en notebook-fil eller instrumentpanel som körs igen med olika parametrar.
Utforska snabbt resultatet av en enskild fråga med olika parametrar.

Om du vill visa dokumentationen för widget-API:et i Scala, Python eller R använder du följande kommando: dbutils.widgets.help()

Det finns 4 typer av widgetar:

text: Ange ett värde i en textruta.
dropdown: Välj ett värde i en lista med angivna värden.
combobox: Kombination av text och listruta. Välj ett värde från en angivet lista eller ange ett i textrutan.
multiselect: Välj ett eller flera värden i en lista med angivna värden.

Listrutor och textrutor för widgetar visas direkt efter verktygsfältet för notebook-filer. Widgetar accepterar endast strängvärden.

Om du vill skapa en widget väljer du Redigera > lägg till widget. I dialogrutan Lägg till widget anger du widgetens namn, valfri etikett, typ, parametertyp, möjliga värden och valfritt standardvärde. I dialogrutan är Parameternamn det namn som du använder för att referera till widgeten i koden. Widgetetikett är ett valfritt namn som visas över widgeten i användargränssnittet.

När du har skapat en widget kan du hovra över widgetnamnet för att visa ett verktygstips som beskriver hur du refererar till widgeten.

Du kan använda menyn för att redigera eller ta bort widgeten:

Använda Databricks-widgetar i ett beräkningskluster

I det här avsnittet beskrivs hur du använder Databricks-widgetar i en notebook-fil som är kopplad till ett beräkningskluster. Information om hur du använder widgetar i en notebook-fil som är kopplad till ett SQL-lager finns i Använda Databricks-widgetar i ett SQL-lager.

Widget-API:et är utformat för att vara konsekvent i Scala, Python och R. Widget-API:et i SQL skiljer sig något, men motsvarar de andra språken. Du hanterar widgetar via referensgränssnittet för Databricks Utilities (dbutils).

Det första argumentet för alla widgettyper är name. Det här är det namn som du använder för att komma åt widgeten.
Det andra argumentet är defaultValue, widgetens standardinställning.
Det tredje argumentet är för alla widgettyper förutom text är choices, en lista med värden som widgeten kan använda. Det här argumentet används inte för text typwidgetar.
Det sista argumentet är label, ett valfritt värde för etiketten som visas över widgetens textruta eller listruta.

Om du vill se detaljerad API-dokumentation för varje metod använder du dbutils.widgets.help("<method-name>"). Hjälp-API:et är identiskt på alla språk. Till exempel:

dbutils.widgets.help("dropdown")

Skapa en enkel listrutewidget.

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

Interagera med widgeten från widgetpanelen.

Du kan komma åt det aktuella värdet för widgeten med anropet:

Python

dbutils.widgets.get("state")

SQL

SELECT "${state}"

Slutligen kan du ta bort en widget eller alla widgetar i en notebook-fil:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Om du tar bort en widget kan du inte skapa en widget i samma cell. Du måste skapa widgeten i en annan cell.

Spark SQL använder widgetvärden som strängliteraler som kan användas i frågor.

Du kan komma åt widgetar som definierats på valfritt språk från Spark SQL när du kör notebook-filer interaktivt. Överväg följande arbetsflöde:

Skapa en listrutewidget för alla databaser i den aktuella katalogen:

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

Skapa en textwidget för att manuellt ange ett tabellnamn:
```
dbutils.widgets.text("table", "")
```
Kör en SQL-fråga för att se alla tabeller i en databas (markerad i listrutan):
```
SHOW TABLES IN ${database}
```
Ange ett tabellnamn manuellt i widgeten table .
Förhandsgranska innehållet i en tabell utan att behöva redigera innehållet i frågan:
```
SELECT *
FROM ${database}.${table}
LIMIT 100
```

Kommentar

I allmänhet kan du inte använda widgetar för att skicka argument mellan olika språk i en notebook-fil. Du kan skapa en widget arg1 i en Python-cell och använda den i en SQL- eller Scala-cell om du kör en cell i taget. Detta fungerar dock inte om du använder Kör alla eller kör notebook-filen som ett jobb.

Provisoriska lösningar:

För notebook-filer som inte blandar språk kan du skapa en notebook-fil för varje språk och skicka argumenten när du kör notebook-filen.
- Du kan komma åt widgeten med hjälp av ett spark.sql() anrop. Till exempel i Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

Kommentar

Om du vill undvika $ tecknet i en SQL-strängliteral använder du \$. Om du till exempel vill uttrycka strängen $1,000använder du "\$1,000". Tecknet $ kan inte undantagas för SQL-identifierare.

Använda Databricks-widgetar i ett SQL-lager

I det här avsnittet beskrivs hur du använder Databricks-widgetar i en notebook-fil som är kopplad till ett SQL-lager. Information om hur du använder widgetar i en notebook-fil som är kopplad till ett beräkningskluster finns i Använda Databricks-widgetar i ett beräkningskluster.

Om du vill referera till widgetvärden i ett SQL-lager använder du syntaxen :param, inte $param. Om du till exempel har en widget med namnet fare_amount använder du kod som liknar följande:

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

Använd nyckelordet IDENTIFIER för att identifiera objekt som tabeller, vyer, scheman och kolumner. Om widgeten med namnet table_name till exempel är inställd på samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Mer information finns i IDENTIFIER-sats.

Mer information om parametermarkörsyntaxen finns i Parametermarkörer.

Du kan konfigurera beteendet för widgetar när ett nytt värde väljs, om widgetpanelen alltid är fäst överst i anteckningsboken och ändra layouten för widgetar i notebook-filen.

Klicka på ikonen till höger i widgetpanelen.
Välj widgetens körningsbeteende i popup-widgetpanelen Inställningar dialogrutan.
- Kör notebook-fil: Varje gång ett nytt värde väljs körs hela notebook-filen igen.
- Kör använda kommandon: Varje gång ett nytt värde väljs körs endast celler som hämtar värdena för den specifika widgeten igen. Det här är standardinställningen när du skapar en widget. SQL-celler körs inte på nytt i den här konfigurationen.
- Gör ingenting: Varje gång ett nytt värde väljs körs ingenting igen.
Om du vill fästa widgetarna överst i anteckningsboken eller placera widgetarna ovanför den första cellen klickar du på . Inställningen sparas per användare. Klicka på tumtackikonen igen för att återställa till standardbeteendet.
Om du har behörigheten KAN HANTERA för notebook-filer kan du konfigurera widgetlayouten genom att klicka på . Varje widgets ordning och storlek kan anpassas. Om du vill spara eller stänga dina ändringar klickar du på .

Widgetlayouten sparas med notebook-filen. Om du ändrar widgetlayouten från standardkonfigurationen läggs inte nya widgetar till i alfabetisk ordning.
Om du vill återställa widgetlayouten till en standardordning och storlek klickar du för att öppna dialogrutan Widgetpanel Inställningar och klickar sedan på Återställ layout. Kommandot removeAll() återställer inte widgetlayouten.

Exempelnotebook-fil

Du kan se en demonstration av hur inställningen Kör åtkomstkommandon fungerar i följande notebook-fil. Widgeten year skapas med inställningen 2014 och används i DataFrame API- och SQL-kommandon.

När du ändrar inställningen för widgeten year till 2007körs DataFrame-kommandot igen, men SQL-kommandot körs inte igen.

Den här notebook-filen illustrerar användningen av widgetar i en notebook-fil som är kopplad till ett kluster, inte ett SQL-lager.

Hämta notebook-fil