Widżety usługi Databricks

Artykuł
06/28/2024

Widżety wejściowe umożliwiają dodawanie parametrów do notesów i pulpitów nawigacyjnych. Widżet można dodać z interfejsu użytkownika usługi Databricks lub przy użyciu interfejsu API widżetu. Aby dodać lub edytować widżet, musisz mieć uprawnienia CAN EDIT w notesie.

Jeśli używasz środowiska Databricks Runtime 11.3 LTS lub nowszego, możesz również użyć poleceń ipywidgets w notesach usługi Databricks.

Widżety usługi Databricks są najlepsze dla:

Tworzenie notesu lub pulpitu nawigacyjnego, który jest ponownie wykonywany przy użyciu różnych parametrów.
Szybkie eksplorowanie wyników pojedynczego zapytania z różnymi parametrami.

Aby wyświetlić dokumentację interfejsu API widżetu w języku Scala, Python lub R, użyj następującego polecenia: dbutils.widgets.help()

Istnieją 4 typy widżetów:

text: Wprowadź wartość w polu tekstowym.
dropdown: Wybierz wartość z listy podanych wartości.
combobox: kombinacja tekstu i listy rozwijanej. Wybierz wartość z podanej listy lub wprowadź wartość w polu tekstowym.
multiselect: Wybierz co najmniej jedną wartość z listy podanych wartości.

Listy rozwijane widżetu i pola tekstowe są wyświetlane natychmiast po pasku narzędzi notesu. Widżety akceptują tylko wartości ciągu.

Tworzenie widgetów

W tej sekcji pokazano, jak tworzyć widżety przy użyciu interfejsu użytkownika lub programowo przy użyciu magii SQL lub interfejsu API widżetu dla języków Python, Scala i R.

Tworzenie widżetów przy użyciu interfejsu użytkownika

Tworzenie widżetu przy użyciu interfejsu użytkownika notesu. Jeśli masz połączenie z usługą SQL Warehouse, jest to jedyny sposób tworzenia widżetów.

Wybierz pozycję Edytuj > widżet Dodaj. W oknie dialogowym Dodawanie widżetu wprowadź nazwę widżetu, opcjonalną etykietę, typ, typ parametru, możliwe wartości i opcjonalną wartość domyślną. W oknie dialogowym Nazwa parametru jest nazwą używaną do odwołowania się do widżetu w kodzie. Etykieta widżetu to opcjonalna nazwa wyświetlana nad widżetem w interfejsie użytkownika.

Po utworzeniu widżetu możesz umieścić wskaźnik myszy na nazwie widżetu, aby wyświetlić etykietkę narzędzia opisjącą sposób odwołowania się do widżetu.

Możesz użyć menu kebab, aby edytować lub usunąć widżet:

Tworzenie widżetów przy użyciu języków SQL, Python, R i Scala

Programowe tworzenie widżetów w notesie dołączonym do klastra obliczeniowego.

Interfejs API widżetu został zaprojektowany tak, aby był spójny w języku Scala, Python i R. Interfejs API widżetu w języku SQL jest nieco inny, ale równoważny z innymi językami. Widżety można zarządzać za pomocą interfejsu referencyjnego narzędzia usługi Databricks (dbutils).

Pierwszym argumentem dla wszystkich typów widżetów jest name. Jest to nazwa używana do uzyskiwania dostępu do widżetu.
Drugi argument to defaultValue, domyślne ustawienie widżetu.
Trzecim argumentem dla wszystkich typów widżetów (z wyjątkiem text) jest choiceslista wartości, które może przyjąć widżet. Ten argument nie jest używany dla text widżetów typu.
Ostatnim argumentem jest label, opcjonalna wartość etykiety wyświetlanej w polu tekstowym widżetu lub liście rozwijanej.

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

Interakcja z widżetem z panelu widżetu.

Możesz uzyskać dostęp do bieżącej wartości widżetu lub uzyskać mapowanie wszystkich widżetów:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Na koniec możesz usunąć widżet lub wszystkie widżety w notesie:

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

Jeśli usuniesz widżet, nie możesz go utworzyć w tej samej komórce. Widżet należy utworzyć w innej komórce.

Wartości widżetów dostępu do usług Spark SQL i SQL Warehouse przy użyciu znaczników parametrów. Znaczniki parametrów chronią kod przed atakami polegającymi na wstrzyknięciu kodu SQL przez wyraźne oddzielenie podanych wartości od instrukcji SQL.

Znaczniki parametrów dla widżetów są dostępne w środowisku Databricks Runtime 15.2 lub nowszym. Poprzednie wersje środowiska Databricks Runtime powinny używać starej składni dla DBR 15.1 i nowszych.

Możesz uzyskiwać dostęp do widżetów zdefiniowanych w dowolnym języku z usługi Spark SQL podczas interaktywnego wykonywania notesów. Rozważmy następujący przepływ pracy:

Utwórz widżet listy rozwijanej wszystkich baz danych w bieżącym wykazie:

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

Utwórz widżet tekstowy, aby ręcznie określić nazwę tabeli:
```
dbutils.widgets.text("table", "")
```
Uruchom zapytanie SQL, aby wyświetlić wszystkie tabele w bazie danych (wybrane z listy rozwijanej):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Uwaga

Należy użyć klauzuli SQL IDENTIFIER() , aby przeanalizować ciągi jako identyfikatory obiektów, takie jak nazwy baz danych, tabel, widoków, funkcji, kolumn i pól.
Ręcznie wprowadź nazwę tabeli w widżecie table .
Utwórz widżet tekstowy, aby określić wartość filtru:
```
dbutils.widgets.text("filter_value", "")
```

Wyświetl podgląd zawartości tabeli bez konieczności edytowania zawartości zapytania:

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

W tej sekcji opisano sposób przekazywania wartości widżetów usługi Databricks do %sql komórek notesu w środowisku Databricks Runtime 15.1 lub nowszym.

Tworzenie widżetów w celu określenia wartości tekstowych.

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"

Przekaż wartości widżetu ${param} przy użyciu składni .

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

Uwaga

Aby uciec od $ znaku literału ciągu SQL, użyj polecenia \$. Aby na przykład wyrazić ciąg $1,000, użyj polecenia "\$1,000". Nie $ można uniknić znaku dla identyfikatorów SQL.

Zachowanie widżetów można skonfigurować po wybraniu nowej wartości, niezależnie od tego, czy panel widżetu jest zawsze przypięty do góry notesu, i zmieniać układ widżetów w notesie.

Kliknij ikonę na prawym końcu panelu Widżet.
W wyskakującym oknie dialogowym Ustawienia panelu widżetu wybierz zachowanie wykonywania widżetu.
- Uruchom notes: za każdym razem, gdy jest zaznaczona nowa wartość, cały notes jest uruchamiany ponownie.
- Uruchom polecenia z dostępem: za każdym razem, gdy jest zaznaczona nowa wartość, uruchamiane są tylko komórki pobierające wartości dla tego konkretnego widżetu. Jest to ustawienie domyślne podczas tworzenia widżetu. Komórki SQL nie są uruchamiane ponownie w tej konfiguracji.
- Nic nie robi: za każdym razem, gdy jest zaznaczona nowa wartość, nic nie jest uruchamiane ponownie.
Aby przypiąć widżety do góry notesu lub umieścić widżety nad pierwszą komórką, kliknij przycisk . Ustawienie jest zapisywane dla poszczególnych użytkowników. Kliknij ponownie ikonę kciuka, aby zresetować domyślne zachowanie.
Jeśli masz uprawnienie CAN MANAGE dla notesów, możesz skonfigurować układ widżetu, klikając pozycję . Kolejność i rozmiar każdego widżetu można dostosować. Aby zapisać lub odrzucić zmiany, kliknij pozycję .

Układ widżetu jest zapisywany za pomocą notesu. Jeśli zmienisz układ widżetu z konfiguracji domyślnej, nowe widżety nie zostaną dodane alfabetycznie.
Aby zresetować układ widżetu do domyślnej kolejności i rozmiaru, kliknij , aby otworzyć okno dialogowe Ustawienia panelu widżetów, a następnie kliknij przycisk Resetuj układ. Polecenie removeAll() nie resetuje układu widżetu.

Przykładowy notes

W poniższym notesie pokazano, jak działa ustawienie Uruchom dostępne polecenia . Widżet year jest tworzony za pomocą ustawienia 2014 i jest używany w interfejsie API ramki danych i poleceniach SQL.

Po zmianie ustawienia widżetu year na 2007polecenie DataFrame zostanie ponownie uruchomione polecenie , ale polecenie SQL nie zostanie ponownie uruchomione.

Ten notes ilustruje użycie widżetów w notesie dołączonym do klastra, a nie w usłudze SQL Warehouse.

Pobierz notes