Verwenden von Parameterwidgets

Wenn Sie einer Abfrage eine benannte Parametermarkierung hinzufügen, zeigt Azure Databricks ein Parameter-Widget in der Benutzeroberfläche an. Widgets ermöglichen Benutzern das Festlegen von Parameterwerten, ohne die Abfrage direkt zu bearbeiten. Sie können den Typ, den Titel und den Standardwert jedes Widgets konfigurieren.

Parameter-Widgets werden in folgenden Bereichen unterstützt: im SQL-Editor, in Notebooks, in AI/BI-Dashboards und in Genie-Räumen, verhalten sich jedoch auf diesen Oberflächen unterschiedlich. Diese Seite beschreibt Parameter-Widgets im SQL-Editor. Weitere Oberflächen finden Sie unter:

• Arbeiten mit Dashboardparametern für Dashboards
• Verwenden von Parametern in SQL-Abfragen für Genie-Räume
• Databricks-Widgets für Notebooks

Im SQL-Editor kann jeder Parametertyp (String, Integer, Decimal, Date, Timestamp) jeden Widgettyp verwenden.

Konfigurieren eines Parameter-Widgets

1. Fügen Sie Ihrer Abfrage eine benannte Parametermarkierung hinzu. Ein Widget wird auf der Benutzeroberfläche angezeigt.
2. Klicken Sie auf das Zahnradsymbol neben dem Widget, um das Widget-Dialogfeld zu öffnen.
3. Legen Sie die folgenden Felder fest:
   • Parametername: Der Parametername, wie er in der Abfrage angezeigt wird. Wenn Sie den Parameternamen ändern, müssen Sie ihn auch im Widget-Dialogfeld in der Abfrage ändern.
   • Widgetbezeichnung: Eine Zeichenfolge, die das Widget beschrieben hat
   • Widgettyp: Steuert, wie Benutzer den Wert eingeben. Siehe Widget-Typen unten.
   • Parametertyp: Der Parameterdatentyp. Siehe Parametertypen.
4. Klicken Sie außerhalb des Widget-Dialogfelds, um Ihre Änderungen zu speichern.

Bearbeiten, Entfernen und Neuanordnen von Widgets

Bearbeiten: Klicken Sie auf das Zahnradsymbol neben dem Widget, um den Einstellungsbereich erneut zu öffnen.

Remove: Entfernen Sie das Parametermarkierung aus der Abfrage. Das Widget wird automatisch entfernt.

Neu anordnen: Verwenden Sie den Ziehpunkt links neben einem Widget, um die Anordnung neu anzuordnen.

Widgettypen

Azure Databricks unterstützt die folgenden Widgettypen für Abfrageparameter:

Texteingabe

Akzeptiert einen Freiformwert direkt vom Benutzer. Verwenden Sie dieses Widget, wenn keine vordefinierten Optionen erforderlich sind.

SELECT * FROM samples.tpch.region WHERE r_name = :region_param

Dropdown

Stellt eine vordefinierte Liste von Werten dar. Benutzer müssen aus der Liste auswählen – der Freiformeintrag ist nicht zulässig. Geben Sie im Einstellungsbereich zulässige Werte ein, eine pro Zeile.

SELECT * FROM samples.tpch.orders WHERE o_orderstatus = :status_param

So erstellen Sie einen Dropdown-Widgettyp:

1. Klicken Sie neben dem :status_param Widget auf das Zahnradsymbol.
2. Legen Sie den Widgettyp auf "Dropdown" fest.
3. Legen Sie den Parametertyp auf "String" fest.
4. Geben Sie Werte in das Auswahlmöglichkeiten für Parameterwert Text-Eingabefeld ein. Klicken Sie auf "Hinzufügen" , oder drücken Sie die EINGABETASTE zwischen jedem Wert.

Kombinationsfeld

Stellt eine vordefinierte Liste der vorgeschlagenen Werte dar, ermöglicht benutzern jedoch auch die Eingabe eines benutzerdefinierten Werts, der nicht in der Liste enthalten ist. Verwenden Sie ein Kombinationsfeld, wenn allgemeine Optionen für die Benutzerfreundlichkeit nützlich sind, aber Sie möchten Freiformeingaben zulassen.

SELECT * FROM samples.tpch.part WHERE p_brand = :brand_param

Mehrfachauswahl

Ermöglicht Benutzern das Auswählen mehrerer Werte aus einer vordefinierten Liste. Die ausgewählten Werte werden als Sammlung an die Abfrage übergeben.

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

So fügen Sie Optionen für eine Dropdownliste mit Mehrfachauswahl hinzu:

1. Klicken Sie neben dem list_parameter Widget auf das Zahnradsymbol.
2. Stellen Sie den Widget-Typ auf Multiselect ein.
3. Legen Sie den Parametertyp auf "String" fest.
4. Geben Sie Werte in das Auswahlfeld für Parameterwerte ein. Klicken Sie auf "Hinzufügen" , oder drücken Sie die EINGABETASTE zwischen jedem Wert.

Dynamische Dropdownliste

Füllt die Liste der Auswahlmöglichkeiten aus einer gespeicherten Abfrage anstelle einer statischen Liste auf. Wenn sich die zugrunde liegenden Daten ändern, werden die verfügbaren Optionen automatisch aktualisiert.

So verwenden Sie ein dynamisches Dropdown:

1. Erstellen und Speichern einer Abfrage, die die gewünschten Werte in der Dropdownliste zurückgibt:

   SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment
   

2. Fügen Sie in einer neuen oder vorhandenen Abfrage eine benannte Parametermarkierung hinzu:

   SELECT c_custkey, c_name, c_acctbal
   FROM samples.tpch.customer
   WHERE c_mktsegment = :segment_param
   

3. Klicken Sie neben dem segment_param Widget auf das Zahnradsymbol.

4. Legen Sie den Widget-Typ auf "Dynamische Dropdownliste" fest.

5. Klicken Sie auf das Abfragefeld, um das Dialogfeld "Vorhandene Abfrage auswählen " zu öffnen. Wählen Sie die gespeicherte Abfrage aus Schritt 1 aus, und klicken Sie dann auf "Auswählen".

6. Wählen Sie einen Standardwert aus.

7. Klicken Sie auf Apply Changes.

Datums- und Zeitstempelbereich

Datums- und Zeitstempelparameter unterstützen einen Widget-Typ namens Range. Wenn diese Option ausgewählt ist, erstellt Azure Databricks zwei Parameter mit .min und .max Suffixen, um den Anfang und das Ende des Bereichs zu definieren.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Klicken Sie auf das blaue Blitzsymbol, um dynamische Werte wie today, yesterday, this week, last week, last month oder last year auszuwählen. Diese Werte werden automatisch aktualisiert.