Databricks-Widgets

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.

Verwenden Sie zum Anzeigen der Dokumentation für die Widget-API in Scala, Python oder R den folgenden Befehl: dbutils.widgets.help() Sie können auch auf die Dokumentation zum Widgets-Dienstprogramm (dbutils.widgets) verweisen.

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.

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.

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.

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

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.

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
   

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

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

   

   • 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 . 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 klicken. Die Reihenfolge und Größe jedes Widgets kann angepasst werden. Klicken Sie auf , 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 , 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.

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.

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

Weitere Informationen finden Sie unter Bekannte Einschränkungen von Databricks-Notebooks.