Databricks-widgetar

Artikel
10/31/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(). Du kan också läsa dokumentationen om widgetverktyget (dbutils.widgets).

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.

Skapa widgets

Det här avsnittet visar hur du skapar widgetar med hjälp av användargränssnittet eller programmässigt med antingen SQL-magi eller widget-API:et för Python, Scala och R.

Skapa widgetar med hjälp av användargränssnittet

Skapa en widget med hjälp av notebook-användargränssnittet. Om du är ansluten till ett SQL-lager är det här det enda sättet att skapa widgetar.

Välj 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 en knappbeskrivning som beskriver hur du refererar till widgeten.

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

Skapa widgetar med SQL, Python, R och Scala

Skapa widgetar programmatiskt i en notebook-fil som är kopplad till ett beräkningskluster.

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 defaultValuewidgetens standardinställning.
Det tredje argumentet för alla widgettyper (utom 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.

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

Interagera med widgeten från widgetpanelen.

Du kan komma åt det aktuella värdet för widgeten eller hämta en mappning av alla widgetar:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

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

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Spark SQL och SQL Warehouse får åtkomst till widgetvärden med hjälp av parametermarkörer. Parametermarkörer skyddar koden från SQL-inmatningsattacker genom att tydligt separera angivna värden från SQL-uttrycken.

Parametermarkörer för widgetar finns i Databricks Runtime 15.2 och senare. Tidigare versioner av Databricks Runtime bör använda den gamla syntaxen för DBR 15.1 och senare.

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 IDENTIFIER(:database)
```
Kommentar

Du måste använda SQL-satsen IDENTIFIER() för att parsa strängar som objektidentifierare, till exempel namn för databaser, tabeller, vyer, funktioner, kolumner och fält.
Ange ett tabellnamn manuellt i widgeten table .
Skapa en textwidget för att ange ett filtervärde:
```
dbutils.widgets.text("filter_value", "")
```

Förhandsgranska innehållet i en tabell utan att behöva redigera innehållet i frågan:

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

I det här avsnittet beskrivs hur du skickar Databricks-widgetvärden till %sql notebook-celler i Databricks Runtime 15.1 och nedan.

Skapa widgetar för att ange textvärden.

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"

Skicka in widgetvärdena med hjälp av syntaxen ${param} .

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

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.

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.
I dialogrutan Inställningar för widgetpanelen i popup-fönstret väljer du widgetens körningsbeteende.
- 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 inga nya widgetar till i alfabetisk ordning.
Om du vill återställa widgetlayouten till en standardordning och storlek klickar du på för att öppna dialogrutan Inställningar för widgetpanelen och klickar sedan på Återställ layout. Kommandot removeAll() återställer inte widgetlayouten.