Filtervorlagen und Liquid-Parameter

Dieses Thema für Fortgeschrittene richtet sich an Benutzer, die bereits über gute SQL- und LookML-Kenntnisse verfügen.

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

Aus SQL-Perspektive können Dimensionen und Messwerte nur die äußersten WHERE- oder HAVING-Klauseln in der Abfrage ändern. Vielleicht möchten Sie aber auch, dass die Benutzer andere Teile des SQL-Codes bearbeiten können. Das Anpassen eines Teils einer abgeleiteten Tabelle, das Anpassen der abgefragten Datenbanktabelle oder das Erstellen von Mehrzweckdimensionen und -filtern sind nur einige der Funktionen, die Sie mit Filtervorlagen und Liquid-Parametern aktivieren können.

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

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-Parametern zu veranschaulichen.

Eine dynamische abgeleitete Tabelle mit einer Filtervorlage erstellen

Sehen Sie sich eine abgeleitete Tabelle an, mit der die Lifetime-Ausgaben eines Kunden in der Region Nordosten berechnet werden:

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. Angenommen, Sie möchten jedoch, dass der Nutzer region angeben kann, anstatt es für "northeast" hart zu codieren. Die region kann nicht als Dimension dargestellt werden. Daher kann der Nutzer nicht wie gewohnt 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 detaillierte Anleitung finden Sie im Abschnitt Grundlegende Verwendung.

Hinweis: Wenn eine abgeleitete Tabelle eine Filtervorlage verwendet, 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 detaillierte Anleitung finden Sie im Abschnitt Grundlegende Verwendung.

Grundlegende Verwendung

Schritt 1: Etwas erstellen, mit dem die Nutzenden interagieren können

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

In beiden Fällen werden diese Felder dem Nutzer im Field Picker im Abschnitt Nur Filter-Felder angezeigt.

Sowohl das Feld filter als auch das Feld parameter können eine Reihe von untergeordneten Parametern akzeptieren, um ihre Funktionsweise anzupassen. Eine vollständige Liste finden Sie auf der Dokumentationsseite Feldparameter. Es gibt zwei Optionen, die für parameter-Felder besonders erwähnen.

Erstens können parameter-Felder einen speziellen Typ namens ohne Anführungszeichen 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 eine Option namens zulässige Werte, mit der Sie einen nutzerfreundlichen Namen mit dem einzufügenden Wert verknüpfen 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: Nutzereingabe anwenden

Fügen Sie im zweiten Schritt mit Liquid die Filtervorlage oder den Liquid-Parameter nach Bedarf hinzu.

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 für die Nutzereingabe auf „gleich“ gesetzt werden soll. Dies wird weiter unten in diesem Abschnitt ausführlicher erläutert. Wenn Sie LookML verwenden, nutzen Sie die LookML-Syntax ${view_name.field_name}.

Im vorherigen Beispiel, Dynamische abgeleitete Tabelle mit einer Filtervorlage erstellen, wurde Folgendes verwendet:

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

Es ist wichtig, die Interaktion zwischen den Liquid-Tags und dem SQL-Code zu verstehen, den Sie dazwischen schreiben. Diese Vorlagen-Filter-Tags werden immer in einen logischen Ausdruck umgewandelt. Wenn der Nutzer beispielsweise „Northeast“ in den Filter order_region eingibt, wandelt Looker diese Tags so um:

order.region = 'Northeast'

Mit anderen Worten, Looker interpretiert die Benutzereingabe und generiert den entsprechenden logischen Ausdruck.

Hinweis: Dies führt bei Looker-Entwicklern häufig zu Verwirrung. Filtervorlagen ergeben immer einen logischen Ausdruck irgendeiner Art und nicht den einzelnen Wert, der von einem Nutzer eingegeben wird.

Da Filtervorlagen 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 obigen Beispiel alle Werte außer der Region zurückgeben wollten, die der Nutzer ausgewählt hat, 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. Alle Filter, die direkt auf das LookML-Feld angewendet werden, bestimmen den Wert der WHERE-Anweisung:

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 parameter, den Sie im ersten Schritt erstellt haben.

Wenn Sie beispielsweise die Eingabe aus dem Feld parameter in Schritt 1 anwenden möchten, können Sie einen Messwert wie diesen 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 werden Nutzereingaben direkt oder über die Werte, die Sie mit zulässigen Werten definieren, eingefügt.
• Filtervorlagen fügen Werte als logische Anweisungen ein, wie im Abschnitt Filtervorlagen 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 eine logische Anweisung nicht eingefügt werden kann oder Ihnen eine endliche Anzahl von Optionen bekannt ist, die der Nutzer eingeben könnte.