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.

Um die Dokumentation für die Widget-API in Scala, Python oder R anzuzeigen, verwenden Sie 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 Dropdown-Menü. 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

Dropdown-Menüs und Texteingabefelder für Widgets erscheinen direkt nach der Symbolleiste des Notebooks. Widgets akzeptieren nur Zeichenfolgenwerte.

Widgets erstellen

In diesem Abschnitt wird gezeigt, wie Sie Widgets mithilfe der Benutzeroberfläche oder programmgesteuert mithilfe von SQL-Zaubern 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 > Parameter hinzufügen.

Um die Widgeteinstellungen zu bearbeiten, klicken Sie auf das Zahnradsymbol.

Im Dialogfeld "Widgeteinstellungen " können Sie den Widgetnamen, optionale Bezeichnung, Typ, Parametertyp, mögliche Werte und optionalen Standardwert eingeben. 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 über den Widgetnamen fahren, um ein Tooltip anzuzeigen, das erklärt, wie auf das Widget verwiesen wird.

Erstellen Sie Widgets mit SQL, Python, R und Scala

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

Die Widget-API ist so konzipiert, dass sie in Scala, Python und R konsistent ist. Die Widget-API in SQL unterscheidet sich geringfügig, entspricht jedoch den anderen Sprachen. Sie verwalten Widgets über die Referenzschnittstelle von Databricks Utilities (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 lautet defaultValue, 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",  list("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 Databricks Runtime 15.1 und darunter 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
   

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 Dialogfeld "Einstellungen" des Popup-Widgetbereichs das Ausführungsverhalten des Widgets aus.

   

   • Notizbuch ausführen: Führt das gesamte Notizbuch jedes Mal erneut aus, wenn Sie einen neuen Wert auswählen.
   • Ausführen von Zugriffsbefehlen: Führt nur Zellen aus, die die Werte für dieses bestimmte Widget jedes Mal abrufen, wenn Sie einen neuen Wert auswählen. Dies ist die Standardeinstellung beim Erstellen eines Widgets. SQL-Zellen werden in dieser Konfiguration nicht erneut ausgeführt.
   • Do Nothing: Führt nichts erneut aus, wenn Sie einen neuen Wert auswählen.

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 zurückzusetzen.

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 können 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 Notizbuch ausführen , das Widgets enthält, wird das angegebene Notizbuch 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-Notizbüchern ".