Databricks-vezérlők

Cikk
10/29/2024

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-verziójának dokumentációját a következő paranccsal tekintheti meg: dbutils.widgets.help() A widgetek segédprogramjának (dbutils.widgets) dokumentációját is megtekintheti.

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.

Vezérlők létrehozása

Ez a szakasz bemutatja, hogyan hozhat létre widgeteket a felhasználói felületen vagy programozott módon SQL-varázslatok vagy a Pythonhoz, Scalához és R-hez készült widget API használatával.

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

Hozzon létre egy widgetet a jegyzetfüzet felhasználói felületén. Ha SQL-raktárhoz csatlakozik, csak így hozhat létre widgeteket.

Válassza az Edit Add widget (Hozzáadás) > 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.

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

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

Widgetek létrehozása SQL, Python, R és Scala használatával

Programozott módon hozzon létre widgeteket egy számítási fürthöz csatolt jegyzetfüzetben.

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.
Az összes widgettípus (kivéve text) harmadik argumentuma azoknak choicesaz értékeknek a listája, amelyeken a widget fel tud venni. 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.

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

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

Elérheti a widget aktuális értékét, vagy lekérheti az összes widget leképezését:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

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

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

A Spark SQL és az SQL Warehouse paraméterjelölőkkel érheti el a widgetértékeket. A paraméterjelölők úgy védik a kódot az SQL-injektálási támadásoktól, hogy egyértelműen elválasztják a megadott értékeket az SQL-utasításoktól.

A widgetek paraméterjelölői a Databricks Runtime 15.2-ben és újabb verzióiban érhetők el. A Databricks Runtime korábbi verzióinak a DBR 15.1 és újabb verzióinak régi szintaxisát kell használniuk.

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:

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

Hozzon létre egy szöveg widgetet a táblanév manuális megadásához:
```
dbutils.widgets.text("table", "")
```
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 IDENTIFIER(:database)
```
Feljegyzés

Az SQL-záradék IDENTIFIER() használatával objektumazonosítóként kell elemeznie a sztringeket, például az adatbázisok, táblák, nézetek, függvények, oszlopok és mezők nevét.
Adja meg manuálisan a táblázat nevét a table widgetbe.
Szöveg widget létrehozása szűrőérték megadásához:
```
dbutils.widgets.text("filter_value", "")
```

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

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

Ez a szakasz azt ismerteti, hogyan továbbíthatja a Databricks widgetek értékeit %sql a Databricks Runtime 15.1-es és újabb verzióiban lévő jegyzetfüzetcelláknak.

Szövegértékek megadásához hozzon létre widgeteket.

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"

Adja meg a widget értékeit a ${param} szintaxis használatával.

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

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.

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.

Kattintson a Widget panel jobb végén található ikonra.
Az előugró widget panel beállításai párbeszédpanelen válassza ki a widget végrehajtási viselkedését.
- 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.
Ha a widgeteket a jegyzetfüzet tetejére szeretné kitűzni, vagy az első cella fölé szeretné helyezni a widgeteket, kattintson a 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.
Ha rendelkezik a JEGYZETFÜZETEK KEZELÉSE engedéllyel, a widget elrendezését a gombra kattintva konfigurá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 .

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, az új widgetek nem lesznek betűrendben hozzáadva.
Ha alaphelyzetbe szeretné állítani a widget elrendezését az alapértelmezett sorrendre és méretre, kattintson a Widget panel beállításai 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.

Databricks-widgetek az irányítópultokon

Amikor egy jegyzetfüzetből hoz létre irányítópultot bemeneti widgetekkel, az összes widget megjelenik a tetején. Bemutató módban minden alkalommal, amikor frissíti 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.