Freigeben über

Databricks-Widgets

  • Artikel

Mit Eingabewidgets können Sie Ihren Notebooks und Dashboards Parameter hinzufügen. Sie können ein Widget über die Databricks-Benutzeroberfläche oder mithilfe der Widget-API hinzufügen. Um ein Widget hinzuzufügen oder zu bearbeiten, müssen Sie über KANN BEARBEITEN-Berechtigungen für das Notebook verfügen.

Wenn Sie Databricks Runtime 11.3 LTS oder höher ausführen, können Sie auch ipywidgets in Databricks-Notebooks verwenden.

Databricks-Widgets eignen sich am besten für Folgendes:

  • Erstellen eines Notebooks oder Dashboards, das mit unterschiedlichen Parametern erneut ausgeführt wird.
  • Schnelles Untersuchen der Ergebnisse einer einzelnen Abfrage mit unterschiedlichen Parametern.

Zeigen Sie die Dokumentation für die Widget-API in Scala, Python oder R mit dem folgenden Befehl an: dbutils.widgets.help().

Arten von Databricks-Widgets

Es gibt vier Arten von Widgets:

  • text: Eingeben eines Werts in ein Textfeld
  • dropdown: Auswählen eines Werts aus einer Liste bereitgestellter Werte
  • combobox: Kombination aus Textfeld und Dropdownliste: Auswählen eines Werts aus einer bereitgestellten Liste oder Eingeben eines Werts in das Textfeld
  • multiselect: Auswählen eines oder mehrerer Werte aus einer Liste bereitgestellter Werte

Dropdownlisten und Textfelder für Widgets werden unmittelbar unter der Symbolleiste des Notebooks angezeigt. Widgets akzeptieren nur Zeichenfolgenwerte.

Widget im Header

Widgets erstellen

In diesem Abschnitt wird gezeigt, wie Sie Widgets mit der Benutzeroberfläche oder programmgesteuert mithilfe von SQL-Magic-Befehlen oder der Widget-API für Python, Scala und R erstellen.

Erstellen von Widgets mithilfe der Benutzeroberfläche

Erstellen Sie ein Widget mithilfe der Notebook-Benutzeroberfläche. Wenn Sie mit einem SQL-Warehouse verbunden sind, ist dies die einzige Möglichkeit, Widgets zu erstellen.

Wählen Sie Bearbeiten > Widget hinzufügen aus. Geben Sie im Dialogfeld Widget hinzufügen den Widgetnamen, eine optionale Bezeichnung, einen Typ, einen Parametertyp, mögliche Werte und einen optionalen Standardwert ein. Im Dialogfeld ist Parametername der Name, den Sie verwenden, um in Ihrem Code auf das Widget zu verweisen. Die Widgetbezeichnung ist ein optionaler Name, der über dem Widget auf der Benutzeroberfläche angezeigt wird.

erstellen eines Widgetdialogfelds

Nachdem Sie ein Widget erstellt haben, können Sie mit dem Mauszeiger auf den Widgetnamen zeigen, um eine QuickInfo einzublenden, die beschreibt, wie auf das Widget verwiesen wird.

Widget-QuickInfo

Sie können das Kebab-Menü verwenden, um das Widget zu bearbeiten oder zu entfernen:

Widget-Kebab-Menü

Erstellen von Widgets mit SQL, Python, R und Scala

Erstellen Sie Widgets programmgesteuert in einem Notebook, das an einen Computecluster angefügt ist.

In Scala, Python und R ist die Widget-API gleich aufgebaut. Die Widget-API in SQL ist gleichwertig, unterscheidet sich jedoch etwas von den anderen Sprachen. Sie verwalten Widgets über die Schnittstelle Referenz zu Databricks-Hilfsprogrammen (dbutils).

  • Das erste Argument für alle Widgettypen ist name. Dies ist der Name, den Sie für den Zugriff auf das Widget verwenden.
  • Das zweite Argument ist defaultValue. Dies ist die Standardeinstellung des Widgets.
  • Das dritte Argument für alle Widgettypen (außer text) ist choices. Dies ist eine Liste der Werte, die das Widget annehmen kann. Dieses Argument wird nicht für Widgets vom Typ text verwendet.
  • Das letzte Argument ist label, ein optionaler Wert für die Bezeichnung, die über dem Textfeld oder der Dropdownliste des Widgets angezeigt wird.

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

Interagieren Sie mit dem Widget über den Widgetbereich.

Interaktion mit Widget

Sie können auf den aktuellen Wert des Widgets zugreifen oder eine Zuordnung aller Widgets abrufen:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Sie können auch ein Widget oder alle Widgets in einem Notebook entfernen:

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

Wenn Sie ein Widget entfernen, können Sie kein Widget in derselben Zelle erstellen. Sie müssen das Widget in einer anderen Zelle erstellen.

Verwenden von Widgetwerten in Spark SQL und SQL Warehouse

Spark SQL und SQL Warehouse greifen mithilfe von Parametermarkierungen auf Widgetwerte zu. Parametermarkierungen schützen Ihren Code vor Angriffen durch Einschleusung von SQL-Befehlen, da sie die bereitgestellten Werte eindeutig von den SQL-Anweisungen trennen.

Parametermarkierungen für Widgets sind ab Databricks Runtime 15.2 verfügbar. Frühere Versionen von Databricks Runtime sollten die alte Syntax für DBR 15.1 und älter verwenden.

Sie können auf Widgets, die in einer beliebigen Sprache definiert wurden, von Spark SQL aus zugreifen, während Sie Notebooks interaktiv ausführen. Beachten Sie den folgenden Workflow:

  1. Erstellen Sie ein Dropdown-Widget aller Datenbanken im aktuellen Katalog:

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

  2. Erstellen Sie ein Text-Widget, um einen Tabellennamen manuell anzugeben:

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

  3. Führen Sie eine SQL-Abfrage aus, um alle Tabellen in einer Datenbank anzuzeigen (ausgewählt aus der Dropdownliste):

    SHOW TABLES IN IDENTIFIER(:database)

    Hinweis

    Sie müssen die SQL-Klausel IDENTIFIER() verwenden, um Zeichenfolgen als Objektbezeichner für die Namen von Datenbanken, Tabellen, Ansichten, Funktionen, Spalten und Feldern zu parsen.

  4. Geben Sie manuell einen Tabellennamen in das table-Widget ein.

  5. Erstellen Sie ein Textwidget, um einen Filterwert anzugeben:

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

  6. Zeigen Sie eine Vorschau für den Inhalt einer Tabelle an, ohne den Inhalt der Abfrage bearbeiten zu müssen:

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

Verwenden von Widgetwerten in Databricks Runtime 15.1 und älteren Versionen

In diesem Abschnitt wird beschrieben, wie Databricks-Widgetwerte an %sql-Notebookzellen in Databricks Runtime 15.1 und älteren Versionen übergeben werden.

  1. Erstellen Sie Widgets, um Textwerte anzugeben.

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"

  1. Übergeben Sie die Widgetwerte mithilfe der ${param}-Syntax.

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

Hinweis

Um das Zeichen $ in einem SQL-Zeichenfolgenliteral mit einem Escapezeichen zu versehen, verwenden Sie \$. Um die Zeichenfolge "\$1,000" auszudrücken, verwenden Sie beispielsweise $1,000. Das Zeichen $ kann bei SQL-Bezeichnern nicht mit einem Escapezeichen versehen werden.

Konfigurieren von Widget-Einstellungen

Sie können das Verhalten von Widgets konfigurieren, wenn ein neuer Wert ausgewählt wird, festlegen, ob der Widgetbereich immer am oberen Rand des Notebooks angeheftet wird, und das Layout der Widgets im Notebook ändern.

  1. Klicken Sie auf das Symbol Zahnradsymbol ganz rechts im Widgetbereich.

  2. Wählen Sie im Popupdialogfeld mit Einstellungen für den Widgetbereich das Ausführungsverhalten des Widgets aus.

    Widget-Einstellungen

    • Notebook ausführen: Jedes Mal, wenn ein neuer Wert ausgewählt wird, wird das gesamte Notebook erneut ausgeführt.
    • Befehle mit Zugriff ausführen: Jedes Mal, wenn ein neuer Wert ausgewählt wird, werden nur Zellen erneut ausgeführt, die Werte für dieses bestimmte Widget abrufen. Dies ist die Standardeinstellung beim Erstellen eines Widgets. SQL-Zellen werden in dieser Konfiguration nicht erneut ausgeführt.
    • Nichts unternehmen: Jedes Mal, wenn ein neuer Wert ausgewählt wird, erfolgt keine erneute Ausführung.

  3. Um die Widgets am oberen Rand des Notebooks anzuheften oder über der ersten Zelle zu platzieren, klicken Sie auf Anheftsymbol. Die Einstellung wird für jeden Benutzer einzeln gespeichert. Klicken Sie erneut auf das Heftzweckensymbol, um das Standardverhalten wiederherzustellen.

  4. Wenn Sie über die Berechtigung DARF VERWALTEN für Notebooks verfügen, können Sie das Widgetlayout konfigurieren, indem Sie auf Bearbeitungssymbol klicken. Die Reihenfolge und Größe jedes Widgets kann angepasst werden. Klicken Sie auf Symbole zum Akzeptieren und Abbrechen, um Ihre Änderungen zu speichern oder zu verwerfen.

    Das Widgetlayout wird mit dem Notebook gespeichert. Wenn Sie das Widgetlayout gegenüber der Standardkonfiguration ändern, werden neue Widgets nicht alphabetisch hinzugefügt.

  5. Um das Widgetlayout auf eine Standardreihenfolge und -größe zurückzusetzen, klicken Sie auf Zahnradsymbol, um das Dialogfeld Einstellungen für Widgetbereich zu öffnen, und klicken Sie dann auf Layout zurücksetzen. Der Befehl removeAll() setzt das Widgetlayout nicht zurück.

Notebook mit Beispielen

Im folgenden Notebook wird die Funktionsweise der Einstellung Befehle mit Zugriff ausführen demonstriert. Das Widget year wird mit Einstellung 2014 erstellt und in der DataFrame-API sowie in SQL-Befehlen verwendet.

Widgets

Wenn Sie die Einstellung des Widgets year in 2007 ändern, wird der Datenrahmenbefehl erneut ausgeführt, der SQL-Befehl jedoch nicht.

Dieses Notebook veranschaulicht die Verwendung von Widgets in einem Notebook, das an einen Cluster angefügt ist, nicht ein SQL Warehouse.

Demo-Notebook für Widget

Notebook abrufen

Databricks-Widget auf Dashboards

Wenn Sie ein Dashboard von einem Notebook mit Eingabewidgets erstellen, werden alle Widgets oben angezeigt. Im Präsentationsmodus können Sie jedes Mal, wenn Sie den Wert eines Widgets aktualisieren, auf die Schaltfläche Aktualisieren klicken, um das Notebook erneut auszuführen und Ihr Dashboard mit neuen Werten zu aktualisieren.

Dashboard mit Widgets

Verwenden von Databricks-Widgets mit %run

Wenn Sie ein Notebook ausführen, das Widgets enthält, wird das angegebene Notebook mit den Standardwerten des Widgets ausgeführt.

Wenn das Notebook an einen Cluster angefügt ist (kein SQL-Warehouse), können Sie auch Werte an Widgets übergeben. Zum Beispiel:

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

In diesem Beispiel wird das angegebene Notebook ausgeführt, und 10 wird an Widget X und 1 an Widget Y übergeben.

Begrenzungen

  • Die folgenden Grenzwerte gelten für Widgets:

    • In einem Notebook können maximal 512 Widgets erstellt werden.
    • Ein Widgetname ist auf 1024 Zeichen beschränkt.
    • Eine Widgetbezeichnung ist auf 2048 Zeichen beschränkt.
    • Maximal 2048 Zeichen können in ein Text-Widget eingegeben werden.
    • Es kann maximal 1024 Auswahlmöglichkeiten für ein Mehrfachauswahl-, Kombinationsfeld- oder Dropdown-Widget geben.

  • Es gibt ein bekanntes Problem, bei dem ein Widgetstatus nach dem Drücken von Alle ausführen möglicherweise nicht ordnungsgemäß gelöscht wird, auch wenn das Widget im Code gelöscht oder entfernt wurde. In diesem Fall unterscheiden sich der visuelle Zustand des Widgets und sein gedruckter Zustand. Durch das erneute Ausführen der einzelnen Zellen kann dieses Problem umgangen werden. Um dieses Problem vollständig zu vermeiden, empfiehlt Databricks die Verwendung von ipywidgets.

  • Sie sollten nicht direkt auf den Widgetstatus in asynchronen Kontexten wie Threads, Unterprozessen oder Structured Streaming (foreachBatch) zugreifen, da sich der Widget-Status ändern kann, während der asynchrone Code läuft. Wenn Sie in einem asynchronen Kontext auf den Widgetzustand zugreifen müssen, übergeben Sie ihn als Argument. Angenommen, Sie haben den folgenden Code, der Threads verwendet:

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

    Dann sollten Sie es auf diese Weise schreiben:

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

  • Im Allgemeinen können Widgets keine Argumente zwischen verschiedenen Sprachen innerhalb eines Notebooks übergeben. Sie können arg1 für ein Widget in einer Python-Zelle erstellen und in einer SQL- oder Scala-Zelle verwenden, wenn Sie eine Zelle nach der anderen ausführen. Dies funktioniert jedoch nicht, wenn Sie Alle ausführen verwenden oder das Notebook als Auftrag ausführen. Einige Lösungen sind:

    • Für Notebooks, für die keine Sprachen kombiniert werden können, können Sie ein Notebook für jede Sprache erstellen und die Argumente übergeben, wenn Sie das Notebook ausführen.
    • Sie können über einen spark.sql()-Anruf auf das Widget zugreifen. Beispiel für Python: spark.sql("select getArgument('arg1')").take(1)[0][0].