Databricks-vezérlők

  • Cikk

A bemeneti vezérlők lehetővé teszik paraméterek hozzáadását a jegyzetfüzetekhez és irányítópultokhoz. Hozzáadhat egy widgetet a Databricks felhasználói felületéről vagy a widget API használatával. Widget hozzáadásához vagy szerkesztéséhez SZERKESZTÉSi engedélyekkel kell rendelkeznie a jegyzetfüzeten.

Ha Databricks Runtime 11.3 LTS-t vagy újabb verziót futtat, ipywidgeteket is használhat a Databricks-jegyzetfüzetekben.

A Databricks widgetek a legjobbak a következőkhöz:

  • Olyan jegyzetfüzet vagy irányítópult létrehozása, amelyet más paraméterekkel újra végrehajtanak.
  • Egy különböző paraméterekkel rendelkező lekérdezés eredményeinek gyors feltárása.

A Widget API scalai, Python- vagy R-dokumentációjának megtekintéséhez használja a következő parancsot: dbutils.widgets.help()

Databricks-vezérlőtípusok

A widgeteknek 4 típusa van:

  • text: Adjon meg egy értéket egy szövegmezőben.
  • dropdown: Válasszon ki egy értéket a megadott értékek listájából.
  • combobox: Szöveg és legördülő lista kombinációja. Válasszon ki egy értéket egy megadott listából, vagy adjon meg egyet a szövegmezőben.
  • multiselect: Válasszon ki egy vagy több értéket a megadott értékek listájából.

A widgetek legördülő listája és a szövegmezők közvetlenül a jegyzetfüzet eszköztárát követve jelennek meg. A widgetek csak sztringértékeket fogadnak el.

Widget a fejlécben

Widget létrehozása a felhasználói felületen

Widget létrehozásához válassza az Edit Add widget (Vezérlő hozzáadása) lehetőséget>. A Widget hozzáadása párbeszédpanelen adja meg a widget nevét, az opcionális címkét, a típust, a paraméter típusát, a lehetséges értékeket és az opcionális alapértelmezett értéket. A párbeszédpanelen a paraméternév az a név, amelyet a kódban lévő widgetre való hivatkozáshoz használ. A widgetcímke egy opcionális név, amely a felhasználói felületen található widgeten keresztül jelenik meg.

widget létrehozása párbeszédpanel

Miután létrehozott egy widgetet, rámutathat a widget nevére, és megjeleníthet egy eszköztippet, amely leírja, hogyan hivatkozhat a widgetre.

widget elemleírása

A kebab menüben szerkesztheti vagy eltávolíthatja a widgetet:

widget kebab menü

Databricks-widgetek használata számítási fürtön

Ez a szakasz azt ismerteti, hogyan használhatók a Databricks-vezérlők egy számítási fürthöz csatolt jegyzetfüzetben. Ha widgeteket szeretne használni egy SQL-raktárhoz csatolt jegyzetfüzetben, olvassa el a Databricks-vezérlők használata SQL-raktáron című témakört.

Databricks widget API (fürt)

A widget API úgy lett kialakítva, hogy konzisztens legyen a Scalában, a Pythonban és az R-ben. Az SQL widget API-ja kissé eltérő, de egyenértékű a többi nyelvvel. A widgeteket a Databricks Utilities (dbutils) referencia-felületén keresztül kezelheti.

  • Az összes widgettípus első argumentuma a name. Ezt a nevet használja a widget eléréséhez.
  • A második argumentum a defaultValuewidget alapértelmezett beállítása.
  • A harmadik argumentum az összes widgettípusra érvényes, kivéve text azokat choicesaz értékeket, amelyek a widget által alkalmazhatók. Ez az argumentum nem használható típus text widgetekhez.
  • Az utolsó argumentum a labelwidget szövegmezőjén vagy legördülő listájában megjelenő címke opcionális értéke.

Példa a Databricks widgetre (fürt)

Az egyes metódusok részletes API-dokumentációjának megtekintéséhez használja dbutils.widgets.help("<method-name>")a következőt: . A súgó API minden nyelven azonos. Példa:

dbutils.widgets.help("dropdown")

Hozzon létre egy egyszerű legördülő vezérlőt.

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

A widget panelen található widget használata.

Widget használata

A widget aktuális értékét a hívással érheti el:

Python

dbutils.widgets.get("state")

SQL

SELECT "${state}"

Végül eltávolíthat egy widgetet vagy az összes widgetet a jegyzetfüzetből:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Ha eltávolít egy widgetet, nem hozhat létre widgetet ugyanabban a cellában. A widgetet egy másik cellában kell létrehoznia.

Widgetértékek használata a Spark SQL-ben (fürt)

A Spark SQL a lekérdezésekben használható sztringkonstansokként fér hozzá a widgetértékekhez.

A Spark SQL-ből bármilyen nyelven definiált widgetekhez hozzáférhet, miközben interaktívan hajtja végre a jegyzetfüzeteket. Fontolja meg a következő munkafolyamatot:

  1. Hozzon létre egy legördülő vezérlőt az aktuális katalógus összes adatbázisából:

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

  2. Hozzon létre egy szöveg widgetet a táblanév manuális megadásához:

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

  3. Sql-lekérdezés futtatása az adatbázis összes táblájának megtekintéséhez (a legördülő listából kiválasztva):

    SHOW TABLES IN ${database}

  4. Adja meg manuálisan a táblázat nevét a table widgetbe.

  5. A tábla tartalmának előnézete a lekérdezés tartalmának szerkesztése nélkül:

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

Feljegyzés

Általában nem használhat widgeteket, hogy argumentumokat adjanak át a jegyzetfüzet különböző nyelvei között. Létrehozhat egy widgetet arg1 egy Python-cellában, és használhatja egy SQL- vagy Scala-cellában, ha egyszerre egy cellát futtat. Ez azonban nem működik, ha az Összes futtatása vagy a jegyzetfüzet futtatása feladatként fut.

Áthidaló megoldások:

  • Az olyan jegyzetfüzetek esetében, amelyek nem keverik a nyelveket, létrehozhat egy jegyzetfüzetet az egyes nyelvekhez, és a jegyzetfüzet futtatásakor átadhatja az argumentumokat.
    • A widgetet hívással spark.sql() érheti el. Például a Pythonban: spark.sql("select getArgument('arg1')").take(1)[0][0].

Feljegyzés

Ha el szeretné menekülni a $ karaktert egy SQL-sztring literáljában, használja a következőt \$: . Például a sztring $1,000kifejezéséhez használja a következőt "\$1,000": Az $ SQL-azonosítókhoz nem lehet megmenekülni.

Databricks-widgetek használata SQL-raktárban

Ez a szakasz azt ismerteti, hogyan használhatók a Databricks-vezérlők egy SQL-raktárhoz csatolt jegyzetfüzetben. Ha egy számítási fürthöz csatolt jegyzetfüzetben szeretne widgeteket használni, olvassa el a Databricks-vezérlők használata számítási fürtön című témakört.

Ha egy SQL-raktárban lévő widgetértékekre szeretne hivatkozni, használja a szintaxist, nem $parampedig a .:param Ha például egy fare_amount nevű widgettel rendelkezik, használja a következőhöz hasonló kódot:

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

A kulcsszóval IDENTIFIER azonosíthat objektumokat, például táblákat, nézeteket, sémákat és oszlopokat. Ha például a table_name nevű widget a következőre samples.nyctaxi.tripsvan állítva:

SELECT * FROM IDENTIFIER(:table_name)

További részletekért lásd az IDENTIFIER záradékot.

A paraméterjelölő szintaxisával kapcsolatos részletekért tekintse meg a Paraméterjelölőket.

Vezérlőbeállítások konfigurálása

Konfigurálhatja a widgetek viselkedését egy új érték kiválasztásakor, hogy a widgetpanel mindig a jegyzetfüzet tetejére van-e rögzítve, és módosíthatja a widgetek elrendezését a jegyzetfüzetben.

  1. Kattintson a fogaskerék ikon Widget panel jobb végén található ikonra.

  2. Az előugró widgetpanel Gépház párbeszédpanelen válassza ki a widget végrehajtási viselkedését.

    Widget-beállítások

    • Jegyzetfüzet futtatása: Minden alkalommal, amikor új érték van kiválasztva, a teljes jegyzetfüzet újrafut.
    • Hozzáféréssel rendelkező parancsok futtatása: Minden alkalommal, amikor új érték van kijelölve, csak az adott widget értékeit lekérő cellák lesznek újrafuttatva. Ez az alapértelmezett beállítás widget létrehozásakor. Ebben a konfigurációban az SQL-cellák nem futnak újra.
    • Do Nothing: Minden alkalommal, amikor új érték van kijelölve, semmi sem fut újra.

  3. Ha a widgeteket a jegyzetfüzet tetejére szeretné kitűzni, vagy az első cella fölé szeretné helyezni a widgeteket, kattintson rögzítés ikona gombra. A beállítás mentése felhasználónként történik. Kattintson ismét a hüvelykujj ikonra az alapértelmezett viselkedés visszaállításához.

  4. Ha rendelkezik a JEGYZETFÜZETEK KEZELÉSE engedéllyel, a widget elrendezését a gombra kattintva szerkesztés ikonkonfigurálhatja. Az egyes vezérlők sorrendje és mérete testre szabható. A módosítások mentéséhez vagy elvetéséhez kattintson a gombra ikonok elfogadása és lemondása.

    A widget elrendezése a jegyzetfüzettel együtt lesz mentve. Ha az alapértelmezett konfigurációról módosítja a widgetelrendezést, a rendszer nem ad hozzá új widgeteket betűrendben.

  5. Ha alaphelyzetbe szeretné állítani a widgetelrendezést egy alapértelmezett sorrendre és méretre, kattintson fogaskerék ikona Widget panel Gépház párbeszédpanel megnyitásához, majd az Elrendezés visszaállítása parancsra. A removeAll() parancs nem állítja vissza a widget elrendezését.

Példajegyzetfüzet

Az alábbi jegyzetfüzetben megtekintheti a hozzáféréssel rendelkező parancsok futtatása beállítás működését bemutató bemutatót. A year widget a beállítással 2014 jön létre, és a DataFrame API-ban és az SQL-parancsokban használatos.

Vezérlők

Amikor módosítja a year widget 2007beállításait, a DataFrame parancs újrafut, de az SQL-parancs nem fut újra.

Ez a jegyzetfüzet a fürthöz csatolt jegyzetfüzetek widgeteinek használatát mutatja be, nem sql-raktárban.

Widget bemutató jegyzetfüzete

Jegyzetfüzet beszerzése

Databricks-widgetek az irányítópultokon

Amikor olyan jegyzetfüzetből hoz létre irányítópultot, amely bemeneti widgetekkel rendelkezik, az összes widget megjelenik az irányítópult tetején. Bemutató módban minden alkalommal, amikor frissít egy widget értékét, a Frissítés gombra kattintva újra futtathatja a jegyzetfüzetet, és új értékekkel frissítheti az irányítópultot.

Irányítópult widgetekkel

Databricks-vezérlők használata a következővel: %run

Ha widgeteket tartalmazó jegyzetfüzetet futtat, a rendszer a megadott jegyzetfüzetet a widget alapértelmezett értékeivel futtatja.

Ha a jegyzetfüzet egy fürthöz van csatolva (vagyis nem SQL-raktárhoz), az értékeket a widgeteknek is átadhatja. Példa:

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

Ez a példa a megadott jegyzetfüzetet futtatja, és átadja 10 az X vezérlőnek és 1 az Y vezérlőnek.

Korlátozások

  • A vezérlőkre a következő korlátozások vonatkoznak:

    • Legfeljebb 512 widget hozható létre egy jegyzetfüzetben.
    • A widget neve legfeljebb 1024 karakter hosszúságú lehet.
    • A widgetcímke legfeljebb 2048 karakter hosszúságú lehet.
    • Szöveg widgetbe legfeljebb 2048 karakter adható meg.
    • Többválasztós, kombinált lista vagy legördülő vezérlő esetén legfeljebb 1024 választási lehetőség közül választhat.

  • Van egy ismert probléma, amely miatt előfordulhat, hogy a vezérlő állapota a Futtatás az összes billentyű lenyomása után sem teljesen egyértelmű, még akkor sem, ha törli vagy eltávolítja a vezérlőt a kódból. Ha ez történik, a widget vizualizációs állapota és nyomtatott állapota között eltérés jelenik meg. A cellák egyenként történő újrafuttatása megkerülheti ezt a problémát. A probléma teljes elkerülése érdekében a Databricks az ipywidgets használatát javasolja.

  • Nem szabad közvetlenül aszinkron környezetekben, például szálakban, alfolyamatokban vagy strukturált streamelésben (foreachBatch) hozzáférni a widget állapotához, mivel a widget állapota megváltozhat az aszinkron kód futtatása közben. Ha aszinkron környezetben kell hozzáférnie a widget állapotához, adja meg argumentumként. Ha például a következő kóddal rendelkezik, amely szálakat használ:

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

    Ezután a következő módon kell írnia:

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