Freigeben über

Arbeiten mit Dashboardparametern

  • Artikel

In diesem Artikel wird erläutert, wie Sie Parameter in KI/BI-Dashboards nutzen. Wenn Sie stattdessen mehr über Feldfilter erfahren möchten, lesen Sie Filtern nach Feldern.

Mit KI/BI-Dashboard-Parametern 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, was eine effizientere Abfrage und präzisere Analyse zur Folge hat. 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 Canvas des Dashboards. Bei statischen Parametern in Visualisierungs-Widgets werden die Werte von den Autor*innen oder Editor*innen festgelegt. Bei Parametern in Filterwidgets können Dashboard-Betrachter*innen durch Auswahl von Werten in Filterwidgets 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.

Parameter ändern die Abfrage direkt, was leistungsfähig sein kann. Filter für DataSet-Felder können außerdem Dashboard-Interaktivität, mehr Features und eine bessere Leistung bei großen DataSets als Parameter bieten. Siehe Verwenden von 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.

Gif zeigt ein Beispiel für die folgenden Schritte.

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 Zahnradsymbol neben dem Parameternamen. Ein 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 "String", "Date", "Date " und "Time", "Numeric".

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

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

      Hinweis

      Für diese Auswahl ist möglicherweise eine zusätzliche Änderung ihrer Abfrage erforderlich. Siehe "Mehrfachauswahl zulassen".

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

Festlegen eines Standardparameterwerts

Wählen Sie zum Ausführen Ihrer Abfrage einen Standardwert für Ihren Parameter aus, indem Sie ihn in das Textfeld unter dem Parameternamen eingeben. Führen Sie die Abfrage aus, um eine Vorschau der Abfrageergebnisse mit dem angewendeten Parameterwert anzuzeigen. Durch Ausführen der Abfrage wird auch der Standardwert gespeichert. Wenn Sie diesen Parameter mithilfe eines Filter-Widgets auf der Canvas festlegen, wird der Standardwert verwendet, es sei denn, ein neuer Standardwert wird im Filter-Widget angegeben. Siehe Verwenden von Filtern.

Mehrfachauswahl zulassen

Abfragen, die mehrere Auswahlen 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. Wenn die Abfrage ausgeführt wird, werden alle Zeilen zurückgegeben, die die ausgewählten Parameterwerte enthalten.

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

Um Standardwerte festzulegen, geben Sie sie in das Textfeld unter dem Anzeigenamen ein. Wählen Sie den aktuellen Wert aus, bevor Sie den nächsten eingeben.

Standardwerte werden im Editor festgelegt. Mehrere Werte werden durch ein Leerzeichen markiert und voneinander getrennt.

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 .min und .max Suffixe festgelegt werden:

  • Datumsbereich
  • Datums- und Uhrzeitbereich

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

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 Zahnradsymbol neben dem Parameternamen. Geben Sie das Schlüsselwort und den Anzeigenamen ein. Schließen Sie keine Suffixe oder .max Suffixe ein.min.

  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 .min und .max Werten. 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 letzten 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.

Hinweis

Wenn ein Dataset, das in abfragebasierten Parametern verwendet wird, auch in anderen Visualisierungen auf einem Dashboard verwendet wird, ändert die Filterauswahl eines Viewers alle verbundenen Abfragen. Um dies zu vermeiden, sollten Erstellerinnen und Ersteller ein dediziertes Dataset für abfragebasierte Parameter erstellen, die nicht in anderen Visualisierungen im Dashboard verwendet werden.

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 Ihr 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.

Parameter für statische Widgets

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

Das Beispiel in diesem Abschnitt basiert auf einem Dataset, das die samples.nyctaxi.trips Tabelle abfragt. Die gegebene 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 Wochenende erfolgt ist.

Der Abfragetext ist im folgenden Codeblock enthalten, aber die Anweisungen in diesem Abschnitt sind 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

Gehen Sie zum Hinzufügen eines statischen Widget-Parameter zu einer Visualisierung folgendermaßen vor:

  1. Fügen Sie ein Visualisierungs-Widget zur Entwurfsdashboard-Canvas hinzu.

  2. Wählen Sie mit ausgewähltem neuem Widget das parametrisierte Dataset aus der Dropdownliste Dataset im Konfigurationsbereich aus.

  3. Klicken Sie auf " Filter anzeigen". Für Datasets, die Parameter enthalten, wird im Konfigurationsbereich ein Abschnitt "Parameter " angezeigt.

    Ein Bereich zum Konfigurieren der Visualisierung mit der Option zum Auswählen eines Parameters.

  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, damit die Visualisierung mit dem angewendeten neuen Parameter angezeigt wird.

  6. Prüfen Sie Ihr Dashboard.

    Die folgende Abbildung zeigt zwei Visualisierungs-Widgets. Jede wird als Histogramm mit einem statischen Widgetparameter konfiguriert. Das Diagramm auf der linken Seite zeigt die Verteilung der Entfernungen für Reisen ab Wochentagen, während das Diagramm auf der rechten Seite die gleichen Daten für Wochenenden anzeigt. Beide Visualisierungen basieren auf demselben Dataset.

    Zwei Histogramme, die zur Verwendung statischer Parameter auf Widget-Ebene konfiguriert sind, wie beschrieben.

Vergleichen von Daten mithilfe einer Filterbedingung

Sie können eine Filterbedingung hinzufügen, mit der Sie Aggregationen im 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, wobei der angegebene Parameterwert All ist, der nicht in den Daten angezeigt wird. Der erste Teil der Filterbedingung funktioniert genauso wie im vorherigen Beispiel, 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 den Filter effektiv, wenn weder Weekday noch Weekend als Werte weitergegeben 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 der day_type_param-Satz auf All, Weekday, bzw. Weekend festgelegt ist. Anschließend können Dashboard-Viewer jedes Dataset, das nach Tagestyp gefiltert wird, 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 Reiseentfernungen 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 anzuzeigen, die am Wochenende ausgeführt wurden, passen Sie den statischen Parameter an Wochentag an.
  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 Reisen nach Entfernung für Wochenend- und Wochentagsausflüge anzuzeigen.

Eine GIF-Datei, wie im vorherigen Text beschrieben.

Anzeigen von Parametern im Dashboard

Durch das Hinzufügen eines Filters zum Dashboard-Zeichenbereich können Benutzer 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 den Viewern nur Abfrageergebnisse angezeigt, die den Standardwert verwenden, den Sie in der Abfrage festgelegt haben.

So fügen Sie Ihrem Dashboard einen Parameter hinzu:

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

Arbeiten mit Filterwidgets und statischen Parametern

Bei Parametern handelt es sich um feste Werte, die zur Laufzeit in eine Abfrage eingefügt werden. Wenn zwei oder mehr Verweise auf ein und denselben Parameter mit unterschiedlichen Werten festgelegt sind, zeigen bei der Aktualisierung des Dashboards Visualisierungswidgets einen Fehler an, der angibt, welcher Parameter widersprüchliche Werte aufweist. Das kann geschehen, wenn mehrere Filterwidgets denselben Parameter nutzen oder wenn ein statischer Parameter mit einem Filterwidget in Konflikt steht, das eine Viewer-Auswahl 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 bezieht sich :static_param auf einen statischen Parameter, der im Visualisierungswidget und im DataSet-Editor auf „Alle“ festgelegt werden soll. Der Parameter :dash_param ist ein dynamischer Wert, der von einem Filterwidget im Zeichenbereich des Dashboards gesteuert wird. Diese Anweisung sucht nach einem Wert, der als statischer Parameter bereitgestellt wird. Wenn keiner festgelegt ist, wird stattdessen der Wert eines vom Viewer ausgewählten Dashboardparameters verwendet.

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-Stilparameter.

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 zur Veranschaulichung der Verwendungsweise von Parametern in diesen Fällen finden Sie unter Beispiele für die Syntax für benannte Parameter.

Wichtig

Wenn Sie Betrachter*innen den Zugriff auf Daten durch die Auswahl von Parametern wie Tabellen- oder Katalognamen erlauben, kann das zur versehentlichen Offenlegung vertraulicher Informationen führen. Wenn Sie ein Dashboard mit diesen Optionen veröffentlichen, empfiehlt Azure Databricks, Anmeldeinformationen nicht in das veröffentlichte Dashboard einzubetten.