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 in header

Erstellen eines Widgets mithilfe der Benutzeroberfläche

Wählen Sie zum Erstellen eines Widgets 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.

create widget dialog

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

widget tooltip

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

widget kebab menu

Verwenden von Databricks-Widgets auf einem Computecluster

In diesem Abschnitt wird beschrieben, wie Sie Databricks-Widgets in einem Notebook verwenden, das einem Computecluster zugeordnet ist. Informationen zum Verwenden von Widgets in einem Notebook, das an ein SQL Warehouse angefügt ist, finden Sie unter Verwenden von Databricks-Widgets in einem SQL-Warehouse.

Databricks-Widget-API (Cluster)

In Scala, Python und R ist die Widget-API konsistent. 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 gilt für alle Widgettypen, allerdings ist text gleich choices (eine Liste von Werten, die das Widget akzeptiert). 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.

Beispiel für ein Databricks-Widget (Cluster)

Verwenden Sie dbutils.widgets.help("<method-name>"), um eine ausführliche API-Dokumentation für jede Methode anzuzeigen. Die Hilfe-API ist in allen Sprachen gleich. Beispiele:

dbutils.widgets.help("dropdown")

Erstellen Sie ein einfaches Dropdownwidget.

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

Interagieren Sie mit dem Widget über den Widgetbereich.

Interact with widget

Mit dem folgenden Aufruf können Sie auf den aktuellen Wert des Widgets zugreifen:

Python

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

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

Spark SQL greift auf Widgetwerte als Zeichenfolgenliterale zu, die in Abfragen verwendet werden können.

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 ${database}

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

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

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

Hinweis

Im Allgemeinen können Sie keine Widgets verwenden, um Argumente zwischen verschiedenen Sprachen innerhalb eines Notebooks zu ü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.

Problemumgehungen:

  • 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].

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.

Verwenden von Databricks-Widgets in einem SQL-Warehouse

In diesem Abschnitt wird beschrieben, wie Sie Databricks-Widgets in einem Notebook verwenden, das einem SQL Warehouse zugeordnet ist. Informationen zum Verwenden von Widgets in einem Notebook, das an ein Computecluster angefügt ist, finden Sie unter Verwenden von Databricks-Widgets in einem Computecluster.

Verwenden Sie zum Verweisen auf Widgetwerte in einem SQL Warehouse die Syntax :param, anstatt $param. Wenn Sie z. B. ein Widget mit dem Namen fare_amount haben, verwenden Sie einen Code ähnlich dem folgenden:

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

Verwenden Sie das Schlüsselwort IDENTIFIER, um Objekte wie Tabellen, Ansichten, Schemas und Spalten zu identifizieren. Beispiel: Wenn das Widget mit dem Namen table_name auf samples.nyctaxi.tripsfestgelegt ist:

SELECT * FROM IDENTIFIER(:table_name)

Weitere Informationen finden Sie unter IDENTIFIER-Klausel.

Ausführliche Informationen zur Parametermarkierungssyntax finden Sie unter Parametermarkierungen.

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 gear icon ganz rechts im Widgetbereich.

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

    Widget settings

    • 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 pin icon. 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 edit icon klicken. Die Reihenfolge und Größe jedes Widgets kann angepasst werden. Klicken Sie auf accept and cancel icons, 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 in alphabetischer Reihenfolge hinzugefügt.

  5. Um das Widgetlayout auf eine Standardreihenfolge und -größe zurückzusetzen, klicken Sie auf gear icon, 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 Datenrahmen-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 aus einem Notebook mit Eingabewidgets erstellen, werden alle Widgets oben im Dashboard 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 ausführen und Ihr Dashboard mit neuen Werten zu aktualisieren.

Dashboard with 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 (d. h. 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 ausgegebener 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.