Liquid変数の参照

Liquid は、より動的なコンテンツを作成するために Looker で使用できるテンプレート言語です。たとえば、クエリの結果に基づいて外部ツールの URL を作成したり、ユーザーの選択に応じてクエリの対象となるデータベース テーブルを変更したりできます。

Liquid ステートメントは変数、フィルタ、タグから作成されます。変数には使用したい情報が含まれています。このページでは、Looker で提供される変数について説明します。これらの値は、フィルタやタグを使用してさらに変更できます。詳しくは、Liquid のガイドをご覧ください。

LookML では、Liquid を使用できる場所がいくつかあります。

  • action パラメータ
  • フィールドの description パラメータ（Explore 以外のパラメータ）
  • html パラメータ
  • label パラメータ、view_label パラメータ、group_label パラメータ、group_item_label パラメータなどのフィールド レベルのパラメータ
  • link パラメータ
  • sql で始まるパラメータ（sql、sql_on など）
  • default_value ダッシュボード フィルタ パラメータ
  • filters ダッシュボード要素パラメータ

Liquid変数の使用

Liquid 変数の基本的な使用は単純です。使用する変数を特定したら（次のリストを参照）、有効な LookML パラメータに挿入します。特定のLiquid変数は、次の定義に示すように、特定のLookMLパラメーターでのみ使用できます。

Liquidの2つの使用方法

Liquid変数は次の2つの方法で使用できます。

  1. 出力構文: このタイプの使用法ではテキストを挿入でき、Looker で Liquid を使用する最も一般的な方法です。このメソッドでは、Liquid 変数を 2 つの中かっこで囲みます。例: {{ value }}
  2. タグ構文: 通常、このタイプの使用法では、テキストは挿入されず、論理比較やその他の Liquid オペレーションに使用されます。この方法では、Liquid 変数は 1 つの中かっこと 1 つのパーセント記号で囲みます。（例: {% if value > 10000 %}）。

基本的な例

この HTML 使用例では、商品 ID を <img> タグに挿入し、商品画像を生成しています。

dimension: product_image {
  sql: ${product_id} ;;
  html: <img src="https://www.brettcase.com/product_images/{{ value }}.jpg" /> ;;
}

URLでの使用方法を示す次の例では、URLにアーティスト名を挿入することで、そのアーティストに関するGoogle検索を生成しています。

dimension: artist_name {
  sql: ${TABLE}.artist_name ;;
  link: {
    label: "Google"
    url: "https://www.google.com/search?q={{ value }}"
    icon_url: "https://google.com/favicon.ico"
  }
}

この例の SQL 使用例では、ユーザーが選択するフィールドに応じてデータベース テーブルが決定されます。この構文は if を使用します。それ以外の場合は、elsif として示されている else 構造を使用して、クエリに含まれるフィールドを確認して対応します。

sql_table_name:
  {% if event.created_date._in_query %}
    event_by_day
  {% elsif event.created_week._in_query %}
    event_by_week
  {% else %}
    event
  {% endif %} ;;

このラベルの使用例では、LookML のモデル名に応じて、email ディメンションの label の値が変更されています。これにより、フィールド ピッカーと email ディメンションを含むすべてのクエリ結果で、フィールド名が動的に変更されます。

dimension: email {
  label: "{% if _model._name == 'thelook' %} Looker Registered Email Address {% else %} External Email Address {% endif %}"
  type: string
  sql: ${TABLE}.email ;;
}

その他の使用例については、個々の LookML パラメータ ページをご覧ください。

他のフィールドからの変数へのアクセス

Liquid 変数は通常、そのフィールドが使用されるフィールドに基づいています。ただし、その値には、必要に応じて他のフィールドからもアクセスできます。

クエリ結果の同じ行の他のフィールドにアクセスするには、{{ view_name.field_name._liquid-variable-name }} 形式を使用します。_liquid-variable-name は、任意の Looker の Liquid 変数に置き換えます。次のように、変数名の前にアンダースコアを付けないことを確認します。

  • {{ view_name.field_name._value }}
  • {{ view_name.field_name._rendered_value }}
  • {{ view_name.field_name._model._name }}

次の例では、この方法を使用してウェブサイトのURLに別のフィールドからアクセスしています。

dimension: linked_name {
  sql: ${name} ;;
  html: <a href="{{ website.url._value }}" target="_blank">{{ value }}</a> ;;
}

{{ field_name._value }} Liquid 変数構文を使用して別のフィールドを参照すると、参照されるフィールドが SQL クエリの SELECT 句に追加され、GROUP BY 句に追加列として追加されます。これは、参照されているフィールドの値を適切に取得するために必要です。ただし、集計メジャーで予期しない結果が生じる可能性があります。詳しくは、このページの集計メジャーでの Liquid 変数の使用に関するセクションをご覧ください。

Liquid変数の定義

次の表に、LookML で使用できる Liquid 変数を示します。[使用状況] 列には、各 Liquid 変数に使用できる LookML パラメータが示されます。次のオプションがあります。

A = action パラメータで機能します。

DV = default_value（ダッシュボード用）パラメータと連携して機能します。

DE = フィールド レベルの description パラメータで機能しますが、Explore レベルの description では機能しません。

F = filters（ダッシュボード要素用）パラメータと連携して機能します。

H = html パラメータで機能します。

LA = フィールド レベルのラベル パラメータ（label パラメータ、view_label パラメータ、group_label パラメータ、group_item_label パラメータなど）と連携します。ただし、モデル、Explore、ビュー、リファレンスのラインレベルでのラベル パラメータや、link のサブパラメータとしての label では機能しません。

LI = link パラメータで機能します。

S = sql で始まるすべての LookML パラメータ（例: sql、sql_on、sql_table_name）で動作します。

変数 定義 用途 出力例
フィールド値
value データベース クエリによって返されるフィールドの未加工の値。ピボットされたフィールドの値を参照できます。

[使用] 列に示されているパラメータに加えて、action と link パラメータの label サブパラメータで value がサポートされています。		 A H LI 8521935
rendered_value このフィールドの値は、Looker のデフォルトの書式で指定します。

日付形式の構文については、rendered_valueLiquid による簡単な日付形式をご覧ください。

[Usage] 列に表示されるパラメータに加えて、action パラメータと link パラメータの label サブパラメータで rendered_value がサポートされています。		 A H LI $8,521,935.00
filterable_value Looker URL でフィルタとして使用するためにフォーマットされたフィールドの値。

たとえば、「Periaptly, Inc」のような文字列を含む文字列値でフィルタすると、value 変数は「Periaptly」と「Inc」という 2 つの異なる文字列を返します。この問題を解決するには、filterable_value 変数で特殊文字をエスケープして 1 つの文字列（この例では「Periaptly, Inc」）を返します。		 A H LI 8521935
リンク
link Looker のデフォルトのドリルリンクの URL。一部のフィールドにはデフォルト リンクを設定できません。 A H LI S /explore/thelook/orders?fields=orders.order_amount&limit=500
linked_value Looker のデフォルトの書式とデフォルトのリンクが含まれるフィールドの値。メジャーにはデフォルトのリンクがないため、メジャーを linked_value と連携させるには、drill_fields パラメータの構成が必要です。 A H LI 8,521,935.00 ドル
フィルタ
_filters['view_name.field_name'] view_name.field_name で指定するフィールドに適用されるユーザー フィルタ。

_filters['view_name.field_name'] は、派生テーブルの sql パラメータでもサポートされていますが、他の sql パラメータではサポートされていません。

派生テーブルの sql パラメータで _filters['view_name.field_name'] を使用するには、sql_quote Liquid フィルタが必要です。		 A DE H LA LI NOT NULL
{% date_start date_filter_name %} date_filter_name で指定する日付フィルタの開始日。詳しくは、date_start と date_end の使用方法をご覧ください。 S 2017-01-01
{% date_end date_filter_name %} date_filter_name で指定する日付フィルタの終了日。詳しくは、date_start と date_end の使用方法をご覧ください。 S 2017-01-01
{% condition filter_name %}
sql_or_lookml_reference
{% endcondition %} 		filter_name で指定するフィルタの値。SQL として sql_or_lookml_reference に適用されます。この変数は、テンプレート フィルタと条件付き結合で使用されます。 S 例については、テンプレート フィルタに関するドキュメント ページと、sql_on のドキュメント ページの条件付き結合のセクションをご覧ください。
{% parameter parameter_name %} parameter_name で要求するパラメータ フィルタの値。 DE LA S 例については、parameter パラメータのドキュメント ページをご覧ください。
parameter_name._parameter_value parameter_name で要求するパラメータ フィルタの値を論理ステートメントに挿入します。 DE H LA LI S 重要な詳細情報と例については、parameter パラメータのドキュメント ページをご覧ください。
User Attributes
_user_attributes['name_of_attribute'] ユーザー属性が使用されている場合は、クエリを行う特定のユーザーの name_of_attribute で要求するユーザー属性の値。_user_attributes['name_of_attribute'] 変数は、高度なフィルタ構文にも使用できます。 A DE H LA LI S DV F northeast
（たとえば、ユーザー属性が「region」の場合）

別の例については、動的スキーマとテーブル名挿入のユーザー属性の使用に関するヘルプセンター記事をご覧ください。
_localization['localization_key'] ユーザーの言語 / 地域に基づいて、モデルの文字列ファイルで定義されたローカライズ キーに関連付けられた値を返します。 DV F 例については、LookML モデルのローカライズドキュメント ページをご覧ください。
LookMLオブジェクト
_model._name このフィールドのモデルの名前。 A DE H LA LI S thelook
_view._name このフィールドのビューの名前。 A DE H LA LI S orders
_explore._name このフィールドの Explore の名前。 A DE H LA LI S order_items
_explore._dashboard_url 追加 22.12 現在のダッシュボードの相対 URL。H LI /dashboards/5
_field._name フィールド自体の名前（view_name.field_name 形式）。 A DE H LA LI S orders.total_order_amount
Queries
_query._query_timezone クエリが実行されたタイムゾーン。 A DE H LA LI S アメリカ / ロサンゼルス
view_name._in_query ビューのフィールドがクエリに含まれている場合、true を返します。 DE LA LI S true
view_name.field_name._in_query view_name.field_name で要求されたフィールドがクエリデータ テーブルに含まれている、クエリのフィルタに含まれている、または required_fields パラメータを介してクエリに含まれている場合に、true を返します。 DE LA LI S true
view_name.field_name._is_selected view_name.field_name で要求するフィールドがクエリデータ テーブルに含まれている場合、true を返します。 DE LA LI S true
view_name.field_name._is_filtered view_name.field_name で要求するフィールドがクエリのフィルタに含まれている場合、true を返します。 DE LA LI S true

date_start と date_end の使用

Liquid 変数 date_start と date_end は日付によってデータを複数のテーブルに分割するデータベース言語（BigQuery など）にとって非常に有用です。タグ構文の {% date_start date_filter_name %} または {% date_end date_filter_name %} を使用する必要があります。{{ date_start date_filter_name }} または {{ date_end date_filter_name }} の出力構文は使用できません（通常、この構文はテキストの生成に使用されます）。

たとえば、ビューに次のフィールドを作成できます。


filter: new_filter_test{
  type: date
}

dimension: filter_start{
  type: date
  sql: {% date_start new_filter_test %} ;;
}

dimension: filter_end{
  type: date
  sql: {% date_end new_filter_test %} ;;
}

2022 年 4 月 1 日から 2022 年 5 月 25 日の期間を使用して new_filter_test で Explore をフィルタすると、filter_start ディメンションは 2022 年 4 月 1 日、filter_end は 2022 年 5 月 25 日と評価されます。

date_start と date_end については、次の点に注意してください。

  • Liquid 変数の date_filter 部分で指定されたフィルタを使用してユーザーがクエリをフィルタしなかった場合、{% date_start date_filter %} と {% date_end date_filter %} は両方とも NULL と評価されます。

  • Liquid 変数の date_filter 部分に指定されたフィルタの無期限範囲でユーザーがクエリを実行した場合、範囲の自由端は NULL に解決されます。たとえば、例を使用して、ユーザーが new_filter_test を 2022 年 6 月 7 日より前に設定すると、{% date_start date_filter %} の出力は NULL になります。これは、ユーザーが終了日付きで開始日を指定していない範囲を指定しているためです。ユーザーが 2022 年 6 月 7 日以降にnew_filter_testをに設定した場合、{% date_end date_filter %}出力は NULL になります。

Liquid の出力で NULL の結果が表示される可能性のあるシナリオでは、データベース言語に応じて、NULL 値（IFNULL、COALESCE など）を考慮できるよう、必ず sql パラメータに SQL 関数を含めてください。

date_start と date_end の Liquid 変数を使用して日付パーティション分割テーブルを処理する方法については、Looker コミュニティの date_start と date_end の使用 をご覧ください。

「date_start」と「date_end」を柔軟に分析し、期間に基づく分析を柔軟に比較できるヘルプセンターの

_in_query、_is_selected、_is_filtered の使用

この例に示すように、_in_query、_is_selected、_is_filtered の各変数は、true または false のいずれかの値を提供します。したがって、Liquid変数の参照形式を適切に選択することが重要です。

何らかの要素がクエリに含まれているかどうかを判別し、それに基づいて特定のテキストを挿入する場合は、次のようなパターンを使用する必要があります。

{% if view_name.field_name._in_query %}
  something to insert if true
{% else %}
  something to insert if false
{% endif %}

「true」または「false」という単語をそのまま挿入する場合は、次のようなパターンを入力します。

{{ view_name.field_name._in_query }}

一部の SQL 言語は、文字通り「true」と「false」をサポートしていません。その場合は、sql_boolean フィルタを追加して、必要な true と false の値を取得できます。

{{ view_name.field_name._in_query | sql_boolean }}

_is_selected 変数と _is_filtered 変数についても同じパターンが適用されます。

label パラメータによる Liquid 変数の使用

フィールドの label パラメータで Liquid 変数を使用すると、フィールド ピッカーとビジュアル表示でフィールドの見た目を動的に変更できます。どの Liquid 変数が label パラメータと連携するかを確認するには、このページの表をご覧ください。

Liquid 変数はフィールド レベルのラベル パラメータ（label パラメータ、view_label パラメータ、group_label パラメータ、group_item_label パラメータなど）で機能しますが、モデル、Explore、ビュー、参照行の各レベルのラベル パラメータ、または link のサブパラメータとしてラベルとは機能しません。

次の変数を label と一緒に使用すると、フィールド ピッカー、Explore のデータ セクションの列ヘッダー、ビジュアリゼーションに影響を与えることができます。

  • _model._name
  • _view._name
  • _explore._name
  • _field._name
  • _user_attributes['name_of_attribute']

上の表で LA のマークがあるその他の Liquid 変数（フィルタに基づいて値を返す変数（_filters など）や、変数値を決定する前にクエリの実行を必要とする変数（in_query など））は、フィールド選択ツールのフィールド名を変更しません。このようなケースでは、フィールド名は結果のビジュアリゼーションでのみ変更されます。

label で parameter Liquid 変数を使用する場合、value サブパラメータの値が label に渡されます。

description パラメータによる Liquid 変数の使用

Liquid 変数を description パラメータとともに使用して、フィールドの説明を動的に変更できます。この説明は、ユーザーがフィールド ピッカーのフィールドの情報アイコン、Explore のデータ セクション内のフィールドの列名、テーブルチャート内のフィールドの列名にカーソルを合わせたときに表示されます。どの Liquid 変数が description パラメータで機能するかについては、このページの Liquid 変数の定義セクションの表をご覧ください。

Liquid 変数はフィールド レベルでのみ description パラメータと連動して動作します。Explore レベルの description パラメータでは機能しません。

description とともに次の変数を使用して、フィールド ピッカー、Explore のデータ セクション、テーブルチャートの列見出しに影響を与えることができます。

  • _model._name
  • _view._name
  • _explore._name
  • _field._name
  • _user_attributes['name_of_attribute']

上の表で DE とマークされたその他の Liquid 変数（_filters のようなフィルタに基づいて値を返す Liquid 変数など）や、変数値の前にクエリを実行することを必須としている Liquid 変数（in_query など）は、フィールド選択ツールや Explore のデータ セクションでの説明には影響しません。これらの Liquid 変数は、表グラフ内のフィールドの列見出しにカーソルを合わせたときに表示される説明にのみ影響します。

description パラメータで Liquid を使用する例については、description パラメータのドキュメント ページをご覧ください。

注意点

yesno フィールドの参照

yesno フィールドの値を参照するには、値の大文字と小文字が区別されます。Yes または No を使用します。例:

{% if value == 'Yes' %}

Liquid変数での論理演算子の使用

Liquid 変数には論理演算子 and、or、not を使用できます。Liquid の論理演算子では大文字と小文字が区別され、すべて小文字で記述する必要があります。例:

{% if value == "Shirt" or value == "Shoes" %}
  This is a shirt or shoes.
{% endif %}

「変数が見つかりません」というエラーが表示される

Liquid でこのエラーが表示される理由の 1 つは、次のように {{ }} と {% %} を同時に使用している場合です。 

{% if value > {{ search_latency_top_hr.limit_95._value }} %}

代わりに、次のようにします。

{% if value > search_latency_top_hr.limit_95._value %}

テンプレートフィルターを使用している場合は、派生テーブルに結合していないテーブル名を参照しているかどうかをチェックしてください。

命名規則がクエリのグループ化に影響する場合がある

value という名前のフィールドがある場合、このフィールドは、同じビュー内の別のフィールドで value Liquid 変数が参照されるたびに、Explore クエリの GROUP BY 句に含まれます。

例:

dimension: id {
  primary_key: true
  type: number
  sql: ${TABLE}.id ;;
  html:
    {% if value > 10 %}
      <font color="darkgreen">{{ rendered_value }}</font>
    {% elsif value > 11 %}
      <font color="goldenrod">{{ rendered_value }}</font>
    {% else %}
      <font color="darkred">{{ rendered_value }}</font>
    {% endif %} ;;
}

dimension: value {
  sql: ${TABLE}.status ;;
  type: string
}

これにより、Explore で id のみが選択されている場合、次の SQL が生成されます。

SELECT
orders.id AS orders.id,
orders.status AS orders.value
FROM order_items
LEFT JOIN orders ON order_items.order_id = orders.id

GROUP BY 1,2
ORDER BY orders.id
LIMIT 500

グループ化の挙動を回避するため、value 変数のスコープを、フィールド名から明示的に指定します。

dimension: id {
  primary_key: true
  type: number
  sql: ${TABLE}.id ;;
  html:
    {% if value > 10 %}
      <font color="darkgreen">{{ id._rendered_value }}</font>
    {% elsif value > 11 %}
      <font color="goldenrod">{{ id._rendered_value }}</font>
    {% else %}
      <font color="darkred">{{ id._rendered_value }}</font>
    {% endif %} ;;
}

派生テーブルで _filters['view_name.field_name'] を使用するには、sql_quote が必要です。

SQL 派生テーブルを定義する際に、SQL で値がレンダリングされ、フィルタが文字列値を返す _filters['view_name.field_name'] Liquid 変数を使用する場合は、出力を単一引用符で囲む必要があります。これを行うには、sql_quote Liquid フィルタを追加します。

たとえば、derived_table パラメータの sql パラメータで次のいずれかの Liquid 変数を使用している場合:

{{ _filters['view_name.field_name'] }}

または

{% assign foo = _filters['view_name.field_name']  %} foo

Liquid 変数宣言に Liquid フィルタ | sql_quote を追加できます。

{{ _filters['view_name.field_name'] | sql_quote }}

と

{% assign foo = _filters['view_name.field_name'] | sql_quote %} foo

_filters['view_name.field_name'] 変数を使用する派生テーブルの例を次に示します。

view: users_sql_based_dt {
  derived_table: {
    sql:
    SELECT
      users.id AS id,
          (DATE(users.created_at)) AS created_date,
      users.city AS city,
      COUNT(*) AS user_count
    FROM
        public.users AS users
    {% if users_sql_based_dt.city._is_filtered %}
      WHERE
        users.city = {{ _filters['users_sql_based_dt.city'] | sql_quote  }}
    {% endif %}
    GROUP BY
        1,
        2,
        3
    ORDER BY
        2 DESC
      ;;
  }

city フィールドは SQL に出力される文字列であるため、出力 SQL が単一引用符で囲まれるようにするには、sql_quote Liquid フィルタが必要です。結果の Explore では、ユーザーがフィルタとして都市名を指定すると、都市名を文字列で囲みます。ユーザーが都市の値 New York で Explore クエリをフィルタすると、Looker はこの SQL をデータベースに送信します。

WHERE
    users.city = 'New York'

SQL で値がレンダリングされる派生テーブルの文字列フィールドに _filters['view_name.field_name'] Liquid 変数を使用している場合に Liquid 変数に | sql_quote を付加しないと LookML で次の警告が表示されます。

Using "_filters[]" in Derived Table SQL without "sql_quote" is discouraged.

この構文で sql_quote を使用して、配列内の複数の値を引用符で囲むこともできます。

{{ _filters['view_name.field_name'] |split(",") | sql_quote |join(",") }}

次の例では、Liquid 出力が IN ステートメントの入力として使用されます。

 WHERE
    users.city IN({{ _filters['users_sql_based_dt.city'] |split(",") | sql_quote |join(",") }})

この構文では、Liquid 出力は完全なリスト（'value1, value2, value3'）を引用符で囲むのではなく、個々の値（'value1','value2','value3'）を引用符で囲みます。

集計メジャーの流動変数

メジャーの link または html パラメータで {{ view_name.field_name._value }} 構文または {{ field_name._value }} 構文を使用して別のフィールドから値を参照すると、Looker はそのフィールドを SQL クエリに取得してフィールド値を取得します。このため、Liquid は SQL クエリの生成方法と GROUP BY 句が使用する列の数に影響を与える可能性があります。type: count のメジャーなどの集計メジャーを操作すると、予期しない動作が発生する可能性があります。

たとえば、次の 2 つのメジャーがあるとします。

measure: count_without_liquid {
  type: count
}

measure: count_with_liquid {
  type: count
  link: {
    label: "Status Count"
    url: "https://www.google.com/search?q={{ status._value }}"
  }
}

count_without_liquid メジャーを使用してクエリを生成すると、次の結果が得られます。

[Created Month and Count without Liquid] フィールドが選択されると、クエリのデータテーブルが作成されます。

この場合、クエリは月ごとに 1 つのカウントを返します。次に、前の結果で生成された SQL を示します。

SELECT
  TO_CHAR(DATE_TRUNC('month', order_items.created_at ), 'YYYY-MM') AS "order_items.created_month",
  COUNT(*) AS "order_items.count_without_liquid"
FROM order_items AS order_items

GROUP BY DATE_TRUNC('month', order_items.created_at )
ORDER BY 1 DESC
LIMIT 500

ただし、count_with_liquid メジャーを使用してクエリを生成すると、次の結果が得られます。

[Created Month] と [Count with Liquid] フィールドが選択されたクエリのデータテーブルが作成されます。

この例では、クエリ内の各月ごとの数ではなく、各月のカウントと各ステータスの数を受信しています。これは、生成された SQL では、値を取得できるように status フィールドがクエリに追加されたためです。また、クエリに追加されているため、GROUP BY 句にも追加されています。

SELECT
  TO_CHAR(DATE_TRUNC('month', order_items.created_at ), 'YYYY-MM') AS "order_items.created_month",
    order_items.status AS "order_items.status",
    COUNT(*) AS "order_items.count_without_liquid"
FROM order_items AS order_items

GROUP BY DATE_TRUNC('month', order_items.created_at ),2
ORDER BY 1 DESC
LIMIT 500

これを防ぐ方法として、Liquid 変数を指定した row[] 関数を使用する方法があります。この場合、ブラウザのレンダリング結果から値が取得され、参照先のフィールドが SQL クエリに追加されません。

  link: {
    label: "{% if row['view_name.field_name'] %} some_label {% endif %}"
    url: "https://www.google.com/search?q={{ row['view_name.field_name'] }}"
  }

この構文を使用する場合、link パラメータは、フィールドが選択されているか、または他の方法でクエリに含まれている場合にのみ機能します。

つまり、row[] 構文を使用しても、そのフィールドは {{ field_name._value }} のようにクエリに追加されません。この項目にユーザーがアクセスできない場合、ダイナミック ラベルはリンクにラベルを付加しないため、リンクメニューからリンクが削除されます。