Databricks-vezérlők

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 Scala, Python vagy R widget API dokumentációjának megtekintéséhez használja a következő parancsot: dbutils.widgets.help(). A widgetek segédprogramjának (dbutils.widgets) dokumentációját is megtekintheti.

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

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 widget API használatával Python, Scala és R számára.

Tip

Mondja meg a Genie Code-nak (ügynök módnak), hogy tegye ezt Önért:

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.

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 a Hozzáadási paraméter szerkesztése lehetőséget>.

A widget beállításainak szerkesztéséhez kattintson a fogaskerék ikonra.

A widget beállításai párbeszédpanelen megadhatja 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.

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-t úgy tervezték, hogy konzisztens legyen a Scalában, Python és R-ben. Az SQL widget API-ja kissé eltérő, de egyenértékű a többi nyelvvel. A widgeteket a Databricks Utilities (dbutils) referenciafelületen 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 egy lista, amely tartalmazza azokat az értékeket choices, amelyeket a widget felvehet. 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", 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"))

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.

Widgetértékek használata a Spark SQL-ben és az SQL Warehouse-ban

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 Databricks Runtime 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:

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 IDENTIFIER(:database)
   

   Feljegyzés

   Az SQL IDENTIFIER() záradék használatával sztringeket objektumazonosítóként kell elemeznie, például adatbázisok, táblák, nézetek, függvények, oszlopok és mezők neveként.

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

5. Szöveg widget létrehozása szűrőérték megadásához:

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

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

Widgetértékek használata DDL-sztring-záradékokban

Egyes DDL-záradékok, például a LOCATION elemben található CREATE TABLE záradék, azonosítók helyett karakterlánc-literálokat fogadnak el. Ezekhez a záradékokhoz a IDENTIFIER() záradék nem használható.

A következőkre vonatkozik: Databricks Runtime 18.0 vagy újabb verzió

A Databricks Runtime 18.0-s és újabb verzióiban közvetlenül az alábbi záradékokban használhat widgeteket:

CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path

A következőkre vonatkozik: Databricks Runtime 14.3–17.3 LTS

A korábbi verziókban az utasítás dinamikus felépítésére használható EXECUTE IMMEDIATE . Ha például egy widget neve 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 || '\'';

Feljegyzés

Paraméterjelölő nem ágyazható be sztringkonstansba (például 'abfss://:widget...'). Ehelyett adja át a teljes sztringet egyetlen paraméterként, vagy hozza létre a teljes sztringet egy változóban CONCAT() , majd adja át a függvénynek EXECUTE IMMEDIATE.

További információ a paraméterjelölők DDL-utasításokban való használatáról: Paraméterjelölők a DDL-sztringek záradékaiban.

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 Widget panel jobb végén található ikonra.

2. 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 új érték kiválasztásakor újrafuttatja a teljes jegyzetfüzetet.
   • Hozzáféréssel rendelkező parancsok futtatása: Csak az adott widget értékeit lekérő cellákat futtassa újra minden alkalommal, amikor új értéket választ ki. Ez az alapértelmezett beállítás widget létrehozásakor. Ebben a konfigurációban az SQL-cellák nem futnak újra.
   • Ne tegyen semmit: Nem futtat újra semmit, amikor új értéket választ ki.

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

4. Ha rendelkezik a JEGYZETFÜZETEK KEZELÉSE engedéllyel, a widget elrendezését a kattintva konfigurálhatja. Az egyes widgetek 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.

5. Ha alaphelyzetbe szeretné állítani a widget elrendezését az alapértelmezett sorrendre és méretre, kattintson a a Widget panel beállításai párbeszédpanel megnyitásához, majd kattintson 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.

Databricks-widgetek használata a %run parancssal

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

További információért tekintse meg a Databricks-jegyzetfüzetek ismert korlátozásait .