Share via

Widgety Databricks

  • Článek

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

Typy widgetů Databricks

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.

Widget v záhlaví

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

Dialogové okno pro vytvoření widgetu

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

Popis widgetu

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

widget kebab menu

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

Interakce s widgetem

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.

Použití hodnot widgetů ve Spark SQL a SQL Warehouse

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:

  1. 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()])

  2. Vytvořte textový widget pro ruční zadání názvu tabulky:

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

  3. 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í.

  4. Do widgetu table ručně zadejte název tabulky.

  5. Vytvořte textový widget pro zadání hodnoty filtru:

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

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

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

Použití hodnot widgetů v Databricks Runtime 15.1 a níže

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.

  1. 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"

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

Konfigurace nastavení widgetu

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.

  1. ikona ozubeného kola Klikněte na ikonu na pravém konci panelu widgetů.

  2. V automaticky otevíraných panelech widgetů Nastavení dialogové okno zvolte chování spuštění widgetu.

    Nastavení 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í.

  3. Pokud chcete widgety připnout na začátek poznámkového bloku nebo umístit widgety nad první buňku, klikněte na Ikona připnutí. Nastavení se ukládá na základě jednotlivých uživatelů. Dalším kliknutím na ikonu thumbtacku obnovíte výchozí chování.

  4. Pokud máte oprávnění SPRAVOVAT pro poznámkové bloky, můžete nakonfigurovat rozložení widgetu kliknutím Ikona upravitna 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 přijmout a zrušit ikonytlačí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ě.

  5. Chcete-li obnovit rozložení widgetu na výchozí pořadí a velikost, kliknutím ikona ozubeného kolaotevřete dialogové okno Panel widgetů Nastavení a klikněte na tlačítko Obnovit rozložení. Příkaz removeAll() neobnoví rozložení widgetu.

Příklad poznámkového bloku

Následující poznámkový blok ukazuje, jak funguje nastavení Spustit přístupové příkazy . Widget year se vytvoří s nastavením 2014 a používá se v rozhraní DATAFrame API a příkazech SQL.

Pomůcky

Když změníte nastavení widgetu year na 2007příkaz DataFrame znovu spustí, ale příkaz SQL se znovu nes spustí.

Tento poznámkový blok znázorňuje použití widgetů v poznámkovém bloku připojeném ke clusteru, nikoli SQL Warehouse.

Poznámkový blok s ukázkou widgetu

Získat poznámkový blok

Widgety Databricks na řídicích panelech

Když vytvoříte řídicí panel z poznámkového bloku se vstupními widgety, zobrazí se všechny widgety v horní části. V prezentačním režimu můžete pokaždé, když aktualizujete hodnotu widgetu, kliknout na tlačítko Aktualizovat a znovu spustit poznámkový blok a aktualizovat řídicí panel novými hodnotami.

Řídicí panel s widgety

Použití widgetů Databricks s %run

Pokud spustíte poznámkový blok , který obsahuje widgety, spustí se zadaný poznámkový blok s výchozími hodnotami widgetu.

Pokud je poznámkový blok připojený ke clusteru (ne k SQL Warehouse), můžete také předat hodnoty widgetům. Příklad:

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

Tento příklad spustí zadaný poznámkový blok a předá 10 do widgetu X a 1 do widgetu Y.

Omezení

  • Následující omezení platí pro widgety:

    • V poznámkovém bloku lze vytvořit maximálně 512 widgetů.
    • Název widgetu je omezený na 1024 znaků.
    • Popisek widgetu je omezený na 2048 znaků.
    • Do textového widgetu lze zadat maximálně 2048 znaků.
    • Pro vícenásobný výběr, pole se seznamem nebo rozevírací widget může být maximálně 1024 možností.

  • Existuje známý problém, kdy se po stisknutí klávesy Spustit vše nemusí stav widgetu správně vymazat, a to i po vymazání nebo odebrání widgetu v kódu. Pokud k tomu dojde, zobrazí se nesrovnalosti mezi vizuálem widgetu a vytištěnými stavy. Tento problém můžete obejít opětovným spuštěním buněk jednotlivě. Aby se tomuto problému zabránilo úplně, databricks doporučuje používat nástroje ipywidgets.

  • K stavu widgetu byste neměli přistupovat přímo v asynchronních kontextech, jako jsou vlákna, podprocesy nebo strukturované streamování (foreachBatch), protože stav widgetu se může změnit, když je spuštěn asynchronní kód. Pokud potřebujete získat přístup ke stavu widgetu v asynchronním kontextu, předejte ho jako argument. Pokud máte například následující kód, který používá vlákna:

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

    Pak byste ho měli napsat tímto způsobem:

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

  • Obecně platí, že widgety nemůžou předávat argumenty mezi různými jazyky v poznámkovém bloku. Widget arg1 můžete vytvořit v buňce Pythonu a použít ho v buňce SQL nebo Scala, pokud poběžíte po jedné buňce. To ale nefunguje, pokud jako úlohu použijete Spustit vše nebo spustíte poznámkový blok. Mezi alternativní řešení patří:

    • Pro poznámkové bloky, které nekombinují jazyky, můžete vytvořit poznámkový blok pro každý jazyk a předat argumenty při spuštění poznámkového bloku.
    • K widgetu se dostanete pomocí spark.sql() volání. Například v Pythonu: spark.sql("select getArgument('arg1')").take(1)[0][0].