Widgety Databricks

Článek
12/03/2024

Vstupní widgety umožňují přidávat do poznámkových bloků a řídicích panelů parametry. Widget můžete přidat z uživatelského rozhraní Databricks nebo pomocí rozhraní API widgetu. Pokud chcete přidat nebo upravit widget, musíte mít oprávnění CAN EDIT v poznámkovém bloku.

Pokud používáte Databricks Runtime 11.3 LTS nebo novější, můžete v poznámkových blocích Databricks použít také nástroje ipywidget.

Widgety Databricks jsou nejvhodnější pro:

Vytvoření poznámkového bloku nebo řídicího panelu, který se znovu spustí s různými parametry
Rychlé zkoumání výsledků jednoho dotazu s různými parametry

Pokud chcete zobrazit dokumentaci k rozhraní API widgetu v jazyce Scala, Python nebo R, použijte následující příkaz: dbutils.widgets.help(). Můžete se také podívat na dokumentaci k nástroji widgetů (dbutils.widgets).

Existují 4 typy widgetů:

text: Zadejte hodnotu do textového pole.
dropdown: Vyberte hodnotu ze seznamu zadaných hodnot.
combobox: Kombinace textu a rozevíracího seznamu Vyberte hodnotu ze zadaného seznamu nebo zadejte hodnotu do textového pole.
multiselect: Vyberte jednu nebo více hodnot ze seznamu zadaných hodnot.

Rozevírací seznamy widgetu a textová pole se zobrazí hned za panelem nástrojů poznámkového bloku. Widgety přijímají pouze řetězcové hodnoty.

Vytvoření pomůcek

V této části se dozvíte, jak vytvářet widgety pomocí uživatelského rozhraní nebo programově pomocí magic SQL nebo rozhraní API widgetu pro Python, Scala a R.

Vytváření widgetů pomocí uživatelského rozhraní

Vytvořte widget pomocí uživatelského rozhraní poznámkového bloku. Pokud jste připojení ke službě SQL Warehouse, je to jediný způsob, jak můžete vytvářet widgety.

Vyberte Upravit > widget. V dialogovém okně Přidat widget zadejte název widgetu , volitelný popisek, typ, typ parametru, možné hodnoty a volitelnou výchozí hodnotu. V dialogovém okně je název parametru, který používáte pro odkaz na widget v kódu. Popisek widgetu je volitelný název, který se zobrazí nad widgetem v uživatelském rozhraní.

Po vytvoření widgetu můžete najet myší na název widgetu a zobrazit popis, který popisuje, jak na widget odkazovat.

Pomocí nabídky kebab můžete widget upravit nebo odebrat:

Vytváření widgetů s využitím SQL, Pythonu, R a Scaly

Vytváření widgetů v poznámkovém bloku připojeném k výpočetnímu clusteru prostřednictvím kódu programu

Rozhraní API widgetu je navržené tak, aby bylo konzistentní v jazyce Scala, Python a R. Rozhraní API widgetu v SQL se mírně liší, ale odpovídá ostatním jazykům. Widgety spravujete prostřednictvím referenčního rozhraní nástrojů Databricks (dbutils).

Prvním argumentem pro všechny typy widgetů je name. Toto je název, který používáte pro přístup k widgetu.
Druhým argumentem je defaultValuevýchozí nastavení widgetu.
Třetím argumentem pro všechny typy widgetů (s výjimkou text) je choicesseznam hodnot, které widget může převzít. Tento argument se nepoužívá pro text widgety typu.
Posledním argumentem je labelvolitelná hodnota popisku zobrazeného v textovém poli nebo rozevíracím seznamu widgetu.

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

Interakce s widgetem z panelu widgetu

Můžete získat přístup k aktuální hodnotě widgetu nebo získat mapování všech 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

Nakonec můžete widget nebo všechny widgety v poznámkovém bloku odebrat:

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

Pokud widget odeberete, nemůžete ho vytvořit ve stejné buňce. Widget musíte vytvořit v jiné buňce.

Hodnoty widgetu Spark SQL a SQL Warehouse s využitím značek parametrů Značky parametrů chrání váš kód před útoky prostřednictvím injektáže SQL tím, že jasně oddělují zadané hodnoty od příkazů SQL.

Značky parametrů pro widgety jsou k dispozici v Databricks Runtime 15.2 a vyšší. Předchozí verze Databricks Runtime by měly používat starou syntaxi pro DBR 15.1 a novější.

Při interaktivním spouštění poznámkových bloků můžete přistupovat k widgetům definovaným v libovolném jazyce ze Spark SQL. Zvažte následující pracovní postup:

Vytvořte rozevírací widget pro všechny databáze v aktuálním katalogu:

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

Vytvořte textový widget pro ruční zadání názvu tabulky:
```
dbutils.widgets.text("table", "")
```
Spuštěním dotazu SQL zobrazíte všechny tabulky v databázi (vybrané z rozevíracího seznamu):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Poznámka:

Klauzule SQL IDENTIFIER() musíte použít k analýze řetězců jako identifikátorů objektů, jako jsou názvy databází, tabulek, zobrazení, funkcí, sloupců a polí.
Do widgetu table ručně zadejte název tabulky.
Vytvořte textový widget pro zadání hodnoty filtru:
```
dbutils.widgets.text("filter_value", "")
```

Zobrazte náhled obsahu tabulky, aniž byste museli upravovat obsah dotazu:

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

Tato část popisuje, jak předat hodnoty %sql widgetů Databricks do buněk poznámkového bloku v Databricks Runtime 15.1 a níže.

Vytváření widgetů pro zadání textových hodnot

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"

Předejte hodnoty widgetu ${param} pomocí syntaxe.

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

Poznámka:

Chcete-li uvést $ znak v řetězcovém literálu SQL, použijte \$. Chcete-li například vyjádřit řetězec $1,000, použijte "\$1,000". Znak $ nemůže být uchycený pro identifikátory SQL.

Při výběru nové hodnoty můžete nakonfigurovat chování widgetů, jestli je panel widgetů vždy připnutý na začátek poznámkového bloku, a změnit rozložení widgetů v poznámkovém bloku.

Klikněte na ikonu na pravém konci panelu widgetů.
V automaticky otevíraných dialogových oknech Nastavení panelu widgetů zvolte chování při provádění widgetu.
- Spustit poznámkový blok: Při každém výběru nové hodnoty se celý poznámkový blok znovu spustí.
- Spustit přístupové příkazy: Při každém výběru nové hodnoty se znovu spustí pouze buňky, které načítají hodnoty pro daný widget. Toto je výchozí nastavení při vytváření widgetu. V této konfiguraci se znovu neskutečí buňky SQL.
- Nedělejte nic: Pokaždé, když je vybrána nová hodnota, nic se znovu nes spustí.
Pokud chcete widgety připnout na začátek poznámkového bloku nebo umístit widgety nad první buňku, klikněte na . Nastavení se ukládá na základě jednotlivých uživatelů. Dalším kliknutím na ikonu thumbtacku obnovíte výchozí chování.
Pokud máte oprávnění SPRAVOVAT pro poznámkové bloky, můžete nakonfigurovat rozložení widgetu kliknutím na tlačítko . Pořadí a velikost jednotlivých widgetů je možné přizpůsobit. Chcete-li změny uložit nebo zavřít, klikněte na tlačítko .

Rozložení widgetu se uloží s poznámkovým blokem. Pokud změníte rozložení widgetu z výchozí konfigurace, nebudou nové widgety přidány abecedně.
Chcete-li obnovit rozložení widgetu na výchozí pořadí a velikost, kliknutím otevřete dialogové okno Nastavení panelu widgetů a potom klepněte na tlačítko Obnovit rozložení. Příkaz removeAll() neobnoví rozložení widgetu.