Arbeiten mit Dashboardparametern

Auf dieser Seite wird erläutert, wie Sie Parameter in AI/BI-Dashboards verwenden. Wenn Sie stattdessen mehr über Feldfilter erfahren möchten, lesen Sie die Informationen unter Filtern nach Feldern.

Mit AI/BI-Dashboardparametern können Sie zur Laufzeit verschiedene Werte in Datasetabfragen ersetzen. So können Sie Daten nach Kriterien wie Datumsangaben und Produktkategorien filtern, bevor die Daten in einer SQL-Abfrage aggregiert werden. Die hat eine effizientere Abfrage und präzisere Analyse zur Folge. Parameter können zusammen mit Filter-Widgets eingesetzt werden, damit Dashboards interaktiv werden, oder zusammen mit Visualisierungs-Widgets, damit Datasets einfacher wiederverwendet werden können.

Dashboard-Autoren oder -Editoren fügen Parameter zu Datasets hinzu und verbinden sie mit einem oder mehreren Widgets auf der Dashboard-Canvas. Bei statischen Parametern in Visualisierungs-Widgets werden die Werte von den Autoren oder Editoren festgelegt. Bei Parametern in Filter-Widgets können Personen, die das Dashboard anzeigen, durch Auswahl von Werten in Filter-Widgets zur Laufzeit mit den Daten interagieren. Durch diese Interaktion werden die zugehörigen Abfragen erneut ausgeführt, und es werden Visualisierungen basierend auf den gefilterten Daten angezeigt.

Auswählen zwischen Feldfiltern und Parametern

Parameter ändern die Abfrage direkt, was leistungsfähig sein kann. Filter für Datasetfelder können außerdem Dashboardinteraktivität, mehr Features und eine bessere Leistung bei großen Datasets als Parameter bieten. Weitere Informationen finden Sie unter Soll ich nach einem Feld oder einem Parameter filtern?.

Hinzufügen eines Parameters zu einer Abfrage

Sie müssen mindestens über CAN EDIT-Berechtigungen für das Entwurfsdashboard verfügen, um einem Dashboarddataset einen Parameter hinzuzufügen. Sie können Parameter direkt zu den Datasetabfragen auf der Registerkarte "Daten" hinzufügen.

So fügen Sie einer Abfrage einen Parameter hinzu:

1. Platzieren Sie den Cursor an der Stelle, an der Sie den Parameter in Ihrer Abfrage platzieren möchten.

2. Klicken Sie auf "Parameter hinzufügen", um einen neuen Parameter einzufügen.

   Dadurch wird ein neuer Parameter mit dem Standardnamen parameter erstellt. Um den Standardnamen zu ändern, ersetzen Sie ihn im Abfrage-Editor. Sie können auch Parameter hinzufügen, indem Sie diese Syntax im Abfrage-Editor eingeben.

Einen Abfrageparameter bearbeiten

So bearbeiten Sie einen Parameter:

1. Klicken Sie auf Neben dem Parameternamen. Das Dialogfeld Parameterdetails mit den folgenden Konfigurationsoptionen wird angezeigt:

   • Schlüsselwort: Das Schlüsselwort, das den Parameter in der Abfrage darstellt. Dies kann nur geändert werden, indem der Text in der Abfrage direkt aktualisiert wird.

   • Anzeigename: Der Name im Filter-Editor. Standardmäßig entspricht der Titel dem Schlüsselwort.

   • Typ: Zu den unterstützten Typen gehören Zeichenfolge, Datum, Datum und Uhrzeit, Numerisch.

     • Der Standardtyp ist String.
     • Mit dem Datentyp Numerisch können Sie zwischen Dezimalzahl und Ganzzahl unterscheiden. Der standardmäßige numerische Typ ist "Dezimalwert".

   • Mehrfachauswahl zulassen: Aktivieren Sie das Kontrollkästchen, damit Benutzende zur Laufzeit mehrere Parameter auswählen können.

     Hinweis

     Für diese Auswahl ist möglicherweise eine zusätzliche Änderung Ihrer Abfrage erforderlich. Weitere Informationen finden Sie unter Mehrfachauswahl zulassen.

2. Klicken Sie auf einen anderen Teil der Benutzeroberfläche, um das Dialogfeld zu schließen.

Festlegen eines Standardparameterwerts

Geben Sie zum Testen der Abfrage einen Standardwert in das Textfeld unter dem Parameternamen ein, und führen Sie die Abfrage aus. Dadurch wird der Parameterwert angewendet, sodass Sie eine Vorschau der Ergebnisse anzeigen und bestätigen können, dass die Abfrage wie erwartet ausgeführt wird. Durch Ausführen der Abfrage wird auch der Standardwert gespeichert.

Wenn Sie den Parameter in einem Filter-Widget verwenden, wird der Standardwert auf der Registerkarte "Daten " verwendet, es sei denn, das Widget gibt einen anderen Standardwert an. Weitere Informationen finden Sie unter Verwenden von Filtern.

Dashboardautoren sollten bestätigen, dass parametrisierte Abfragen erfolgreich mit den ausgewählten Standardwerten auf der Registerkarte "Dataset" ausgeführt werden. Azure Databricks fragt das Datasetschema ab, um den Widgetkonfigurations-Editor aufzufüllen. In einigen Fällen, insbesondere bei parametrierten Abfragen, die die IDENTIFIER-Klausel verwenden, kann die Abfrage des Datasets mit den Standardparameterwerten fehlschlagen, selbst wenn sie erfolgreich ausgeführt würde, wenn ein Benutzer zur Laufzeit einen Wert auswählt.

Mehrfachauswahl zulassen

Abfragen, die eine Mehrfachauswahl zulassen, müssen eine ARRAY_CONTAINS-Funktion in der Abfrage enthalten.

Das folgende Beispiel zeigt eine SQL-Abfrage, mit der Sie mehrere Werte auswählen können, die zur Laufzeit in die Abfrage eingefügt werden sollen. Die WHERE-Klausel verwendet die ARRAY_CONTAINS-Funktion. Diese Funktion verwendet das Parameterschlüsselwort und den Spaltennamen als Argumente. Der Parameter muss so festgelegt werden, dass mehrere Werte aufbewahrt werden, damit er als Array in die Abfrage eingefügt werden kann. Wenn die Abfrage ausgeführt wird, wird jede Zeile ausgewertet, und alle Zeilen, bei denen mindestens ein Wert in l_quantity mit :parameter übereinstimmt, werden im Resultset enthalten.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

So legen Sie Standardwerte fest:

1. Schreiben Sie eine Datasetabfrage, die die ARRAY_CONTAINS-Funktion verwendet, um Zeilen basierend auf einer Liste von Werten zu filtern.

2. Klicken Sie auf auf das Zahnradsymbol neben dem Parameternamen. Wählen Sie Mehrfachauswahl zulassen aus.

   Hinweis

   In diesem Schritt kann der Parameter als Array in die Abfrage eingefügt werden. Wenn die ARRAY_CONTAINS-Funktion verwendet wird, ohne mehrere Auswahlen zu aktivieren, tritt ein Fehler auf.

3. Geben Sie einen Wert in das Textfeld unter dem Anzeigenamen ein. Sie können mehrere Werte eingeben. Wählen Sie den aktuellen Wert aus, bevor Sie den nächsten eingeben.

Anwenden von Datumsbereichsparametern

Sie können Parameter verwenden, um einen Bereich zu definieren und nur Ergebnisse innerhalb dieses Bereichs zurückzugeben. Wenn Sie einen der folgenden Parametertypen auswählen, erstellen Sie zwei Parameter, die durch die Suffixe .min und .max festgelegt werden:

• Datumsbereich
• Datums- und Zeitbereich

Das folgende Beispiel zeigt eine SQL-Abfrage, die einen Datumsbereichsparameter mit dem Namen date_param erstellt.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

So erstellen Sie einen Datumsbereichsparameter

1. Klicken Sie auf Parameter hinzufügen.

2. Klicken Sie auf Neben dem Parameternamen. Geben Sie Schlüsselwort und Anzeigename ein. Schließen Sie nicht die Suffixe .min oder .max ein.

3. Wählen Sie Datumsbereich oder Datums- und Uhrzeitbereich als Typ aus.

4. Fügen Sie eine WHERE-Klausel ein, die den Bereich in Ihre Abfrage definiert. Verwenden Sie zum Definieren des Bereichs eine BETWEEN-Klausel mit den Werten .min und .max. Zum Beispiel:

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
   

5. Geben Sie Standarddatumswerte ein, und führen Sie die Abfrage aus, um sie zu testen. Verwenden Sie das Kalendersymbol, um voreingestellte Optionen wie „letzte Woche“ oder „letzter Monat“ auszuwählen.

Abfragebasierte Parameter

Abfragebasierte Parameter ermöglichen Erstellerinnen und Erstellern das Definieren einer dynamischen oder statischen Liste von Werten, aus denen Viewer beim Einstellen von Parametern auswählen können, während sie sich Daten in einem Dashboard ansehen. Sie werden durch Kombinieren eines Feldfilters und eines Parameterfilters in einem einzelnen Filter-Widget definiert.

Zum Erstellen eines abfragebasierten Parameters führt die Dashboard-Erstellerin oder der Dashboard-Ersteller die folgenden Schritte aus:

1. Erstellen Sie ein Dataset, dessen Resultset auf eine Liste möglicher Parameterwerte beschränkt ist.
2. Erstellen Sie eine Datasetabfrage, die einen Parameter verwendet.
3. Konfigurieren Sie ein Filter-Widget auf dem Canvas, das nach einem Feld filtert und einen Parameter verwendet.
   • Die Felder-Konfigurationen sollten so festgelegt werden, dass das Feld mit der gewünschten Liste der zulässigen Parameterwerte verwendet wird.
   • Die Parameter-Konfiguration sollte festgelegt werden, um einen Parameterwert auszuwählen.

Eine schrittweise Anleitung zum Hinzufügen eines abfragebasierten Parameters und einer Visualisierung finden Sie unter Verwenden von abfragebasierten Parametern.

Erstellen einer Liste dynamischer Parameter

Um ein dynamisches Dataset zu erstellen, das die Dropdown-Liste auffüllt, die Viewer für die Auswahl von Parameterwerten verwenden, schreiben Sie eine SQL-Abfrage, die ein einzelnes Feld zurückgibt und alle Werte in diesem Feld enthält. Jeder neue Wert in diesem Feld wird automatisch als Parameterauswahl hinzugefügt. Ein SQL-Abfragebeispiel lautet wie folgt:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Erstellen einer Liste statischer Parameter

Sie können ein statisches Dataset erstellen, das nur Werte enthält, die Sie in Ihrem Dataset hartcodieren. Ein Abfragebeispiel lautet wie folgt:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Entfernen eines Abfrageparameters

Um einen Parameter zu entfernen, löschen Sie ihn aus Ihrer Abfrage.

Statische Widget-Parameter

Statische Widget-Parameter werden direkt in einem Visualisierungs-Widget konfiguriert, sodass Autoren Visualisierungs-Widgets, die dasselbe Dataset nutzen, einzeln parametrisieren können. Dadurch kann dasselbe Dataset unterschiedliche Ansichten auf der Canvas darstellen.

Das Beispiel in diesem Abschnitt basiert auf einem Dataset, das die Tabelle samples.nyctaxi.trips abfragt. Die angegebene Abfrage gibt die Entfernung für jede Fahrt zurück und kategorisiert den Abholtag entweder als Weekday oder Weekend. Der Abfrageparameter filtert die Ergebnisse ausgehend davon, ob die Abholung an einem Wochentag oder am Wochenende erfolgt ist.

Der Abfragetext ist im folgenden Codeblock angegeben. Die Anweisungen in diesem Abschnitt sind jedoch auf das Einrichten der zugehörigen Visualisierungen beschränkt, die mit statischen Widget-Parametern konfiguriert sind. Anweisungen zum Einrichten eines Datasets mit Parametern finden Sie unter Hinzufügen eines Parameters zu einer Abfrage.

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

So fügen Sie einer Visualisierung einen statischen Widget-Parameter hinzu

1. Hinzufügen eines Visualisierungs-Widgets zur Entwurfs-Dashboard-Canvas.

2. Wählen Sie das neue Widget und dann das parametrisierte Dataset aus der Dropdownliste Dataset im Konfigurationsbereich aus.

3. Klicken Sie auf Filter anzeigen. Bei Datasets, die Parameter enthalten, wird im Konfigurationsbereich der Abschnitt Parameter angezeigt.

   

4. Klicken Sie rechts neben der Überschrift Parameter auf das Pluszeichen, und wählen Sie einen Parameter aus der Dropdownliste aus.

5. Standardmäßig spiegelt der Parameterwert wieder, was in der Abfrage auf der Registerkarte Daten festgelegt ist. Sie können ihn beibehalten oder einen neuen Wert auswählen, um ihn im Dataset zu ersetzen. Navigieren Sie vom Textfeld weg, um die Visualisierung mit dem angewendeten neuen Parameter anzuzeigen.

6. Überprüfen Sie Ihr Dashboard.

   Die folgende Abbildung zeigt zwei Visualisierungs-Widgets. Beide sind als Histogramm mit einem statischen Widget-Parameter konfiguriert. Das Diagramm auf der linken Seite zeigt die Verteilung der Fahrtentfernungen für Fahrten an Wochentagen, während das Diagramm auf der rechten Seite die gleichen Daten für Wochenenden anzeigt. Beide Visualisierungen basieren auf demselben Dataset.

   

Vergleichen von Daten mithilfe einer Filterbedingung

Sie können eine Filterbedingung hinzufügen, mit der Sie Aggregationen in einem Teil der Daten mit den Aggregationen vergleichen können, die auf das gesamte Dataset angewendet werden.

Im folgenden Beispiel wird die vorherige Abfrage erweitert, um eine Filterbedingung einzuschließen. Dabei ist der angegebene Parameterwert All und wird nicht in den Daten angezeigt. Der erste Teil der Filterbedingung funktioniert genauso wie im vorherigen Beispiel und filtert nach Ergebnissen, wobei day_type entweder Weekday oder Weekend ist. Der zweite Teil der Filterbedingung überprüft, ob der Parameter selbst auf einen bestimmten Wert festgelegt ist, in diesem Fall All, der nicht in den Daten angezeigt wird. Wenn Sie den Standardwert für diesen Parameter im Dataset-Editor festlegen, umgehen Sie effektiv den Filter, wenn weder Weekday noch Weekend als Werte übergeben werden.

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

Sie können dieses Dataset verwenden, um drei Visualisierungs-Widgets zu konfigurieren, wobei day_type_param auf All, Weekday bzw. Weekend festgelegt ist. Anschließend können Personen, die das Dashboard anzeigen, jedes nach Tagestyp gefilterte Dataset mit dem gesamten Dataset vergleichen.

Das folgende GIF zeigt, wie Sie schnell drei Diagramme aus dem Dataset erstellen können, das mit dieser Abfrage erstellt wurde.

1. Das erste Diagramm ist so konfiguriert, dass das Dataset Fahrtentfernungen nach Tagestyp mit einem Parameterwert angezeigt wird, der auf Wochentag festgelegt ist.
2. Klonen Sie das Diagramm, um alle angewendeten Konfigurationen beizubehalten.
3. Um Daten für Fahrten am Wochenende anzuzeigen, ändern Sie den statischen Parameter in Wochenende.
4. Klonen Sie das neue Diagramm, um alle zuvor angewendeten Konfigurationen beizubehalten.
5. Legen Sie den Parameter im neuen Diagramm auf Alle fest, um die Gesamtzahl der Fahrten nach Entfernung für Fahrten am Wochenende und an Wochentagen anzuzeigen.

Anzeigen von Parametern im Dashboard

Durch das Hinzufügen eines Filters zur Dashboard-Canvas können Personen, die das Dashboard anzeigen, Parameterwerte auswählen und ändern, um die Daten interaktiv zu untersuchen und zu analysieren. Wenn Sie den Parameter nicht im Dashboard verfügbar machen, werden Personen, die das Dashboard anzeigen, nur Abfrageergebnisse angezeigt, die den Standardparameterwert verwenden, den Sie in der Abfrage festgelegt haben.

So fügen Sie Ihrem Dashboard einen Parameter hinzu:

1. Klicken Sie auf "Filter hinzufügen" (Feld/Parameter).
2. Klicken Sie auf neben "Parameter" im Konfigurationsbereich.
3. Klicken Sie auf den Parameternamen, den der Viewer mit diesem Widget verwenden soll.

Arbeiten mit Filter-Widgets und statischen Parametern

Bei Parametern handelt es sich um feste Werte, die zur Laufzeit in eine Abfrage eingesetzt werden. Wenn zwei oder mehr Verweise auf denselben Parameter mit unterschiedlichen Werten festgelegt sind, zeigen bei der Aktualisierung des Dashboards Visualisierungs-Widgets einen Fehler mit dem Hinweis an, welcher Parameter widersprüchliche Werte aufweist. Das kann geschehen, wenn mehrere Filter-Widgets denselben Parameter nutzen oder wenn ein statischer Parameter mit einem Filter-Widget in Konflikt steht, das die Auswahl durch anzeigende Personen zulässt.

Sie können ein Muster wie das im folgenden Beispiel verwenden, um Fallbackwerte für verschiedene Parameter in derselben Abfrage festzulegen.

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

In diesem Beispiel :static_param bezieht sich auf einen statischen Parameter, der sowohl im Visualisierungs-Widget als auch im Dataset-Editor auf "Alle" festgelegt werden soll. Der Parameter :dash_param ist ein dynamischer Wert, der von einem Filter-Widget in der Dashboard-Canvas gesteuert wird. Diese Anweisung sucht nach einem Wert, der als statischer Parameter bereitgestellt wird. Wenn keiner festgelegt ist, wird stattdessen der Wert eines Dashboardparameters verwendet, der von einer anzeigenden Person ausgewählt wurde.

Einschließen von Parametern in die URL

Parametereinstellungen werden in der URL gespeichert, sodass Benutzer es mit einer Textmarke versehen können, um den Status ihres Dashboards beizubehalten, einschließlich vordefinierter Filter und Parameter, oder sie für andere freizugeben, um dieselben Filter und Parameter konsistent anzuwenden.

Dashboardparameter im Vergleich zu Mustache-Abfrageparametern

Dashboardparameter verwenden dieselbe Syntax wie benannte Parametermarkierungen. Siehe Benannte Parametermarkierungen. Dashboards unterstützen keine Mustache-Parameter.

Syntaxbeispiele

Zu den gängigen Anwendungsfällen für Parameter gehört das Einfügen von Datumsangaben, Zahlen, Text, Datenbankobjekten und Werten aus JSON-Zeichenfolgen. Beispiele, die die Verwendung von Parametern in diesen Fällen veranschaulichen, finden Sie unter Beispiele für benannte Parametersyntax.