Filtervorlagen und Liquid-Parameter

Dieses Thema richtet sich an fortgeschrittene Benutzer mit guten Vorkenntnissen über SQL und LookML.

Looker bietet Nutzern automatisch die Möglichkeit, ihre Abfragen durch Erstellen von Filtern zu bearbeiten, die auf Dimensionen und Messwerten beruhen. Diese Methode deckt zwar viele Anwendungsfälle ab, kann jedoch nicht alle Analyseanforderungen erfüllen. Durch Filtervorlagen und Liquid-Parameter nimmt die Zahl der möglichen Anwendungsfälle, die Sie unterstützen können, enorm zu.

Aus SQL-Perspektive können Dimensionen und Messwerte lediglich die äußersten WHERE- bzw. HAVING-Klauseln der Abfrage ändern. Vielleicht möchten Sie aber auch, dass die Benutzer andere Teile des SQL-Codes bearbeiten können. Sie können beispielsweise einen Teil einer abgeleiteten Tabelle anpassen, festlegen, welche Datenbanktabelle abgefragt wird, oder Mehrzweckdimensionen und ‑filter erstellen.

Warnung: Persistenz wird für abgeleitete Tabellen, die Filtervorlagen oder Liquid-Parameter verwenden, nicht unterstützt.

Filtervorlagen und Liquid-Parameter verwenden die Liquid-Vorlagensprache, um Benutzereingaben in SQL-Abfragen einzufügen. Zunächst erstellen Sie mithilfe eines LookML-Parameters ein Feld, mit dem Benutzer interagieren können. Als Nächstes verwenden Sie eine Liquid-Variable, um die Benutzereingabe in SQL-Abfragen einzufügen.

Beispiele

Sehen wir uns einige Beispiele an, um den Nutzen von Filtervorlagen und Liquid-Parameter zu veranschaulichen.

Eine dynamische abgeleitete Tabelle mit einer Filtervorlage erstellen

Als Beispiel verwenden wir eine abgeleitete Tabelle, die die Gesamtausgaben eines Kunden (lifetime spend) in der Region Nordost (northeast) berechnet:

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,                        -- Can be made a dimension
        SUM(sale_price) AS lifetime_spend   -- Can be made a dimension
      FROM
        order
      WHERE
        region = 'northeast'                -- Can NOT be made a dimension
      GROUP BY 1
    ;;
  }
}

In dieser Abfrage können Sie Dimensionen aus customer_id und lifetime_spend erstellen. Jetzt nehmen wir jedoch an, dass der Nutzer die region selbst festlegen können soll und die Region daher nicht als „northeast“ fest programmiert wird. Die region kann nicht als Dimension dargestellt werden. Das heißt, der Nutzer kann nicht wie üblich danach filtern.

Eine Option wäre in dem Fall, eine Filtervorlage zu verwenden, die folgendermaßen aussehen würde:

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition order_region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  filter: order_region {
    type: string
  }
}

Eine Schritt-für-Schritt-Anleitung finden Sie im Abschnitt Grundlegende Nutzung.

Hinweis :Wenn in einer abgeleiteten Tabelle ein Filter mit Vorlage verwendet wird, können Sie die Tabelle nicht persistent machen.

Einen dynamischen Messwert mit einem Liquid-Parameter erstellen

Nehmen wir einen gefilterten Messwert als Beispiel, der die Anzahl der verkauften Hosen addiert:

measure: pants_count {
  filters: [category: "pants"]
}

Dieses Verfahren ist leicht nachzuvollziehen, doch hätte man Dutzende Kategorien, würde es eine Menge Aufwand bedeuten, für jede einen Messwert zu erstellen. Zudem wird das Explore dadurch für die Benutzer unübersichtlich.

Als Alternative könnten Sie einen dynamischen Messwert wie folgt erstellen:

measure: category_count {
  type: sum
  sql:
    CASE
      WHEN ${category} = '{% parameter category_to_count %}'
      THEN 1
      ELSE 0
    END
  ;;
}

parameter: category_to_count {
  type: string
}

Eine Schritt-für-Schritt-Anleitung finden Sie im Abschnitt Grundlegende Verwendung.

Grundlegende Nutzung

Erster Schritt: Etwas erstellen, mit dem der Nutzer interagieren kann

• Fügen Sie für Vorlagenfilter eine filter hinzu.
• Fügen Sie für Liquid-Parameter ein parameter hinzu.

In beiden Fällen werden diese Felder dem Nutzer im Field Picker im Abschnitt Reine Filterfelder angezeigt.

Sowohl das Feld filter als auch das Feld parameter können eine Reihe untergeordneter Parameter akzeptieren, sodass Sie deren Funktionsweise anpassen können. Eine vollständige Liste finden Sie auf der Dokumentationsseite Feldparameter. Auf zwei Optionen möchten wir in Bezug auf parameter-Felder besonders hinweisen.

parameter-Felder können einen speziellen Typ namens unquoted haben:

parameter: table_name {
  type: unquoted
}

Mit diesem Typ können Werte in SQL eingefügt werden, ohne von Anführungszeichen umschlossen zu sein, wie es bei einer Zeichenfolge der Fall wäre. Dies kann sinnvoll sein, wenn Sie SQL-Werte wie Tabellennamen einfügen müssen.

Zweitens haben parameter-Felder die Option Zulässige Werte, mit der Sie dem Wert, den Sie einfügen möchten, einen benutzerfreundlichen Namen zuweisen können. Beispiel:

  parameter: sale_price_metric_picker {
    description: "Use with the Sale Price Metric measure"
    type: unquoted
    allowed_value: {
      label: "Total Sale Price"
      value: "SUM"
    }
    allowed_value: {
      label: "Average Sale Price"
      value: "AVG"
    }
    allowed_value: {
      label: "Maximum Sale Price"
      value: "MAX"
    }
    allowed_value: {
      label: "Minimum Sale Price"
      value: "MIN"
    }
  }

Schritt 2: Die Benutzereingabe anwenden

Im zweiten Schritt wird Liquid verwendet, um die Filtervorlage bzw. den Liquid-Parameter wie gewünscht hinzuzufügen.

Filtervorlagen

Die Syntax für Filtervorlagen gestaltet sich wie folgt:

{% condition filter_name %} sql_or_lookml_reference {% endcondition %}

• Die Wörter condition und endcondition ändern sich nie.
• Ersetzen Sie filter_name durch den Namen des Filters, den Sie im ersten Schritt erstellt haben. Sie können auch eine Dimension verwenden, wenn Sie kein Filterfeld erstellen konnten.
• Ersetzen Sie sql_or_lookml_reference durch den SQL- oder LookML-Code, der der Benutzereingabe entsprechen sollte (mehr dazu erfahren Sie weiter unten in diesem Abschnitt). Wenn Sie LookML verwenden, nutzen Sie die LookML-Syntax ${view_name.field_name}.

Im vorherigen Beispiel Eine dynamische abgeleitete Tabelle mit einer Filtervorlage erstellen haben wir Folgendes verwendet:

{% condition order_region %} order.region {% endcondition %}

Es ist wichtig, dass Sie die Interaktion zwischen den Liquid-Tags und dem SQL-Code, den sie dazwischen schreiben, verstehen. Die Tags der Vorlagenfilter werden immer in einen logischen Ausdruck umgewandelt. Wenn der Nutzer beispielsweise im Filter order_region „Northeast“ eingegeben hat, wandelt Looker diese Tags wie folgt um:

order.region = 'Northeast'

Anders ausgedrückt: Looker interpretiert die Benutzereingabe und generiert den entsprechenden logischen Ausdruck.

Hinweis: Dies sorgt unter Looker-Entwicklern oftmals für Verwirrung. Filtervorlagen ergeben immer einen logischen Ausdruck in irgendeiner Form und nicht den einzelnen Wert, den ein Nutzer eingegeben hat.

Da vordefinierte Filter einen logischen Ausdruck zurückgeben, können Sie sie mit anderen logischen Operatoren und logischen Ausdrücken verwenden, die in der SQL-Anweisung WHERE gültig sind. Wenn Sie im vorherigen Beispiel alle Werte mit Ausnahme der Region, die der Nutzer ausgewählt hat, zurückgeben möchten, können Sie Folgendes in der WHERE-Anweisung verwenden:

NOT ({% condition order_region %} order.region {% endcondition %})

Ein LookML-Feld kann auf als Filterbedingung verwendet werden. Mit allen direkt auf das LookML-Feld angewendeten Filtern wird der Wert der WHERE-Anweisung festgelegt.

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  dimension: region {
    type: string
    sql: ${TABLE}.region ;;
}

Liquid-Parameter

Die Syntax für Liquid-Parameter gestaltet sich wie folgt:

{% parameter parameter_name %}

• Das Wort parameter ändert sich nie.
• Ersetzen Sie parameter_name durch den Namen der parameter, die Sie im ersten Schritt erstellt haben.

Soll beispielsweise die Eingabe aus dem Feld parameter im ersten Schritt angewendet werden, könnten Sie eine Kennzahl wie diese erstellen:

  measure: sale_price_metric {
    description: "Use with the Sale Price Metric Picker filter-only field"
    type: number
    label_from_parameter: sale_price_metric_picker
    sql: {% parameter sale_price_metric_picker %}(${sale_price}) ;;
    value_format_name: usd
  }

Zwischen Filtervorlagen und Liquid-Parametern wählen

Zwar ähneln sich Filtervorlagen und Liquid-Parameter, doch es gibt einen entscheidenden Unterschied:

• Mit Liquid-Parametern wird die Nutzereingabe direkt eingefügt (oder es werden die Werte verwendet, die Sie mit zulässigen Werten definieren).
• Bei Filtern mit Vorlagen werden Werte als logische Anweisungen eingefügt, wie im Abschnitt zu Filtern mit Vorlagen beschrieben.

Wenn Sie den Benutzern flexiblere Eingabemöglichkeiten bieten möchten (etwa verschiedene Arten von Datumsbereichen oder Zeichenfolgen-Suchläufen), sollten Sie nach Möglichkeit Filtervorlagen verwenden. Looker kann die Benutzereingabe interpretieren und im Hintergrund den entsprechenden SQL-Code schreiben. So müssen Sie nicht jede nur erdenkliche Benutzereingabe einzeln berücksichtigen.

Verwenden Sie Liquid-Parameter, wenn ein logischer Ausdruck nicht eingefügt werden kann oder die Anzahl der möglichen Benutzereingaben überschaubar ist.