Widgety Databricks

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 také použít ipywidgets v poznámkových blocích Databricks.

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 widgets (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řte widgety

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.

Tip

Řekněte Genie Code (režim agenta), aby to udělal za vás:

Create a new notebook that queries @samples.nyctaxi.trips and displays a bar chart showing the average fare amount by trip distance, grouped by the pickup zip code.

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 Přidat parametr > Upravit.

Pokud chcete upravit nastavení widgetu, klikněte na ikonu ozubeného kola.

V dialogovém okně nastavení widgetu můžete zadat 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.

Vytvářejte widgety pomocí SQL, Python, R a Scala

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ůdbutils Databricks .

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", Seq("CA", "IL", "MI", "NY", "OR", "VA"))

R

dbutils.widgets.dropdown("state", "CA",  list("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 ve widgetu Spark SQL a SQL Warehouse přistupují pomocí 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 Databricks Runtime 15.1 a nižší.

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

Některé klauzule DDL, například LOCATION klauzule v CREATE TABLE, přijímají řetězcové literály místo identifikátorů. Klauzuli IDENTIFIER() pro tyto klauzule nelze použít.

Platí pro: Databricks Runtime zaškrtnuto ano 18.0 a vyšší

V Databricks Runtime 18.0 a novějších můžete použít widgety přímo v těchto klauzulích:

CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path

Platí pro: Databricks Runtime zaškrtnuto ano 14.3 až 17.3 LTS

V dřívějších verzích se používá EXECUTE IMMEDIATE k dynamickému sestavení příkazu. Pokud máte například widget s názvem path:

DECLARE table_location STRING;
SET VARIABLE table_location = CONCAT('abfss://container@account.dfs.core.windows.net/', :path);
EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || table_location || '\'';

Poznámka:

Značku parametru nelze vložit do řetězcového literálu (například 'abfss://:widget...'). Místo toho předejte celý řetězec jako jeden parametr nebo celý řetězec sestavte v proměnné pomocí CONCAT() a potom jej předejte do EXECUTE IMMEDIATE.

Další informace o použití značek parametrů v příkazech DDL naleznete v části Značky parametrů v klauzulích řetězce DDL.

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 na pravém konci panelu widgetů.
V automaticky otevíraných dialogových oknech Nastavení panelu widgetů zvolte chování spuštění widgetu.
- Spustit poznámkový blok: Pokaždé, když vyberete novou hodnotu, znovu spustí celý poznámkový blok.
- Spustit přístupové příkazy: Znovu spustí pouze ty buňky, které načítají hodnoty pro konkrétní widget, pokaždé když zvolíte novou hodnotu. Toto je výchozí nastavení při vytváření widgetu. V této konfiguraci se znovu nespustí buňky SQL.
- Nedělejte nic: Při výběru nové hodnoty se nic neskutečuje znovu.
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 . 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 .

Rozvržení widgetu se uloží spolu 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.