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í widgetu pomocí uživatelského rozhraní

Pokud chcete vytvořit widget, vyberte Upravit > widget Přidat. 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

Použití widgetů Databricks na výpočetním clusteru

Tato část popisuje, jak používat widgety Databricks v poznámkovém bloku připojeném k výpočetnímu clusteru. Pokud chcete použít widgety v poznámkovém bloku připojeném k SQL Warehouse, přečtěte si téma Použití widgetů Databricks ve službě SQL Warehouse.

Rozhraní API widgetu Databricks (cluster)

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í argument je pro všechny typy widgetů kromě textchoices, seznam 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.

Příklad widgetu Databricks (cluster)

Pokud chcete zobrazit podrobnou dokumentaci k rozhraní API pro každou metodu, použijte dbutils.widgets.help("<method-name>"). Rozhraní API nápovědy je ve všech jazycích stejné. Příklad:

dbutils.widgets.help("dropdown")

Vytvořte jednoduchý rozevírací widget.

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

Interakce s widgetem z panelu widgetu

Interakce s widgetem

K aktuální hodnotě widgetu se dostanete voláním:

Python

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

SQL

REMOVE WIDGET state

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

Použití hodnot widgetů ve Spark SQL (clusteru)

Spark SQL přistupuje k hodnotám widgetu jako řetězcové literály, které lze použít v dotazech.

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 ${database}

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

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

    SELECT *
FROM ${database}.${table}
LIMIT 100

Poznámka:

Obecně platí, že widgety nelze použít k předávání argumentů 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.

Alternativní řešení:

  • 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].

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.

Použití widgetů Databricks ve službě SQL Warehouse

Tato část popisuje, jak používat widgety Databricks v poznámkovém bloku připojeném k SQL Warehouse. Pokud chcete použít widgety v poznámkovém bloku připojeném k výpočetnímu clusteru, přečtěte si téma Použití widgetů Databricks ve výpočetním clusteru.

Pokud chcete odkazovat na hodnoty widgetu ve službě SQL Warehouse, použijte syntaxi :param, nikoli $param. Pokud máte například widget s názvem fare_amount, použijte kód podobný následujícímu:

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

IDENTIFIER Klíčové slovo použijte k identifikaci objektů, jako jsou tabulky, zobrazení, schémata a sloupce. Pokud je například widget s názvem table_name nastaven na samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Podrobnosti najdete v klauzuli IDENTIFIER.

Podrobnosti o syntaxi značky parametru najdete v tématu Značky parametrů.

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 v abecedním pořadí.

  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

Ukázku toho, jak funguje nastavení Spustit přístupové příkazy , najdete v následujícím poznámkovém bloku. 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, který obsahuje vstupní widgety, zobrazí se všechny widgety v horní části řídicího panelu. 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 (to znamená ne 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 nesrovnalost mezi vizuálním stavem widgetu a jeho vytištěným stavem. Tento problém můžete obejít opětovným spuštěním buněk jednotlivě. Abyste se tomuto problému zcela vyhnuli, Databricks doporučuje použít ipywidgety.

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