Widżety usługi Databricks

  • Artykuł

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

Typy widżetów usługi Databricks

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.

Widżet w nagłówku

Tworzenie widżetu przy użyciu interfejsu użytkownika

Aby utworzyć widżet, wybierz pozycję Edytuj > dodaj widżet. 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.

Okno dialogowe tworzenia widżetu

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

etykietka narzędzia widżetu

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

menu kebab widżetu

Używanie widżetów usługi Databricks w klastrze obliczeniowym

W tej sekcji opisano sposób używania widżetów usługi Databricks w notesie dołączonym do klastra obliczeniowego. Aby użyć widżetów w notesie dołączonym do usługi SQL Warehouse, zobacz Używanie widżetów usługi Databricks w usłudze SQL Warehouse.

Interfejs API widżetu usługi Databricks (klaster)

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; ustawienie domyślne widżetu.
  • Trzeci argument dotyczy wszystkich typów widżetów z wyjątkiem text : 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.

Przykład widżetu usługi Databricks (klaster)

Aby wyświetlić szczegółową dokumentację interfejsu API dla każdej metody, użyj polecenia dbutils.widgets.help("<method-name>"). Interfejs API pomocy jest identyczny we wszystkich językach. Na przykład:

dbutils.widgets.help("dropdown")

Utwórz prosty widżet listy rozwijanej.

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

Interakcja z widżetem z panelu widżetu.

Interakcja z widżetem

Możesz uzyskać dostęp do bieżącej wartości widżetu za pomocą wywołania :

Python

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

SQL

REMOVE WIDGET state

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

Używanie wartości widżetu w usłudze Spark SQL (klaster)

Usługa Spark SQL uzyskuje dostęp do wartości widżetu jako literałów ciągu, które mogą być używane w zapytaniach.

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:

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

  2. Utwórz widżet tekstowy, aby ręcznie określić nazwę tabeli:

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

  3. Uruchom zapytanie SQL, aby wyświetlić wszystkie tabele w bazie danych (wybrane z listy rozwijanej):

    SHOW TABLES IN ${database}

  4. Ręcznie wprowadź nazwę tabeli w widżecie table .

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

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

Uwaga

Ogólnie rzecz biorąc, nie można używać widżetów do przekazywania argumentów między różnymi językami w notesie. Widżet można utworzyć arg1 w komórce języka Python i użyć go w komórce SQL lub Scala, jeśli jednocześnie uruchomisz jedną komórkę. Nie działa to jednak w przypadku użycia polecenia Uruchom wszystko lub uruchomienia notesu jako zadania.

Obejścia:

  • W przypadku notesów, które nie mieszają języków, można utworzyć notes dla każdego języka i przekazać argumenty podczas uruchamiania notesu.
    • Dostęp do widżetu można uzyskać przy użyciu wywołania spark.sql() . Na przykład w języku Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

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.

Korzystanie z widżetów usługi Databricks w usłudze SQL Warehouse

W tej sekcji opisano sposób używania widżetów usługi Databricks w notesie dołączonym do usługi SQL Warehouse. Aby użyć widżetów w notesie dołączonym do klastra obliczeniowego, zobacz Używanie widżetów usługi Databricks w klastrze obliczeniowym.

Aby odwołać się do wartości widżetów w usłudze SQL Warehouse, użyj składni :param, a nie $param. Jeśli na przykład masz widżet o nazwie fare_amount, użyj kodu podobnego do następującego:

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

Użyj słowa kluczowego IDENTIFIER , aby zidentyfikować obiekty, takie jak tabele, widoki, schematy i kolumny. Jeśli na przykład widżet o nazwie table_name ma ustawioną wartość samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Aby uzyskać szczegółowe informacje, zobacz klauzulę IDENTIFIER.

Aby uzyskać szczegółowe informacje na temat składni znacznika parametrów, zobacz Znaczniki parametrów.

Konfigurowanie ustawień widżetu

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.

  1. Kliknij ikonę ikona koła zębatego na prawym końcu panelu Widżet.

  2. W wyskakującym oknie dialogowym Panel widżetu Ustawienia wybierz zachowanie wykonywania widżetu.

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

  3. Aby przypiąć widżety do góry notesu lub umieścić widżety nad pierwszą komórką, kliknij przycisk ikona pinezki. Ustawienie jest zapisywane dla poszczególnych użytkowników. Kliknij ponownie ikonę kciuka, aby zresetować domyślne zachowanie.

  4. Jeśli masz uprawnienie CAN MANAGE dla notesów, możesz skonfigurować układ widżetu, klikając ikona edycjipozycję . Kolejność i rozmiar każdego widżetu można dostosować. Aby zapisać lub odrzucić zmiany, kliknij pozycję zaakceptuj i anuluj ikony.

    Układ widżetu jest zapisywany za pomocą notesu. Jeśli zmienisz układ widżetu z domyślnej konfiguracji, nowe widżety nie zostaną dodane w kolejności alfabetycznej.

  5. Aby zresetować układ widżetu do domyślnej kolejności i rozmiaru, kliknijikona koła zębatego, aby otworzyć okno dialogowe Panel widżetów Ustawienia, a następnie kliknij przycisk Resetuj układ. Polecenie removeAll() nie resetuje układu widżetu.

Przykładowy notes

W poniższym notesie można zobaczyć pokaz działania ustawienia Uruchom dostępne polecenia . Widżet year jest tworzony z ustawieniem 2014 i jest używany w interfejsie API ramki danych i poleceniach SQL.

Widgety

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.

Notes pokazowy widżetu

Pobierz notes

Widżety usługi Databricks na pulpitach nawigacyjnych

Podczas tworzenia pulpitu nawigacyjnego na podstawie notesu z widżetami wejściowymi wszystkie widżety są wyświetlane w górnej części pulpitu nawigacyjnego. W trybie prezentacji za każdym razem, gdy aktualizujesz wartość widżetu, możesz kliknąć przycisk Aktualizuj , aby ponownie uruchomić notes i zaktualizować pulpit nawigacyjny przy użyciu nowych wartości.

Pulpit nawigacyjny z widżetami

Używanie widżetów usługi Databricks z %run

Jeśli uruchomisz notes zawierający widżety, określony notes zostanie uruchomiony z wartościami domyślnymi widżetu.

Jeśli notes jest dołączony do klastra (czyli nie do usługi SQL Warehouse), możesz również przekazać wartości do widżetów. Na przykład:

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

W tym przykładzie jest uruchamiany określony notes i przechodzi 10 do widżetu X i 1 widżetu Y.

Ograniczenia

  • Następujące limity dotyczą widżetów:

    • W notesie można utworzyć maksymalnie 512 widżetów.
    • Nazwa widżetu jest ograniczona do 1024 znaków.
    • Etykieta widżetu jest ograniczona do 2048 znaków.
    • Do widżetu tekstowego można wprowadzić maksymalnie 2048 znaków.
    • Można wybrać maksymalnie 1024 opcje dla wieloelektowego, pola kombi lub widżetu listy rozwijanej.

  • Istnieje znany problem polegający na tym, że stan widżetu może nie być prawidłowo wyczyszczany po naciśnięciu przycisku Uruchom wszystko, nawet po wyczyszczeniu lub usunięciu widżetu w kodzie. W takim przypadku zobaczysz rozbieżność między stanem wizualizacji widżetu a jego stanem drukowanym. Ponowne uruchomienie komórek indywidualnie może obejść ten problem. Aby całkowicie uniknąć tego problemu, usługa Databricks zaleca użycie widżetów ipywidgets.

  • Nie należy uzyskiwać dostępu do stanu widżetu bezpośrednio w kontekstach asynchronicznych, takich jak wątki, podprocesy lub przesyłanie strumieniowe ze strukturą (foreachBatch), ponieważ stan widżetu może ulec zmianie, gdy kod asynchroniczny jest uruchomiony. Jeśli musisz uzyskać dostęp do stanu widżetu w kontekście asynchronicznym, przekaż go jako argument. Jeśli na przykład masz następujący kod, który używa wątków:

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

    Następnie należy napisać go w ten sposób:

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