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つの方法で使用できます。
- 出力構文: このタイプの使用法ではテキストを挿入でき、Looker で Liquid を使用する最も一般的な方法です。このメソッドでは、Liquid 変数を 2 つの中かっこで囲みます。例:
{{ value }}
- タグ構文: このタイプのテキストは通常、テキストを挿入しませんが、論理比較などの Liquid 操作に使用します。この方法では、Liquid 変数は 1 つの中かっこと 1 つのパーセント記号で囲みます。(例:
{% dynamic 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:
{% dynamic if event.created_date._in_query %}
event_by_day
{% elsif event.created_week._in_query %}
event_by_week
{% dynamic else %}
event
{% dynamic endif %} ;;
このラベルの使用例では、LookML のモデル名に応じて、email
ディメンションの label
の値が変更されています。これにより、フィールド ピッカーと email
ディメンションを含むすべてのクエリ結果で、フィールド名が動的に変更されます。
dimension: email {
label: "{% dynamic if _model._name == 'thelook' %} Looker Registered Email Address {% dynamic else %} External Email Address {% dynamic 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 | データベース クエリによって返されるフィールドの未加工の値。ピボットされたフィールドの値を参照できます。 [使用] 列に示されているパラメータに加えて、 value は action と link パラメータの label サブパラメータでサポートされています。 | A H LI | 8521935 |
rendered_value | このフィールドの値は、Looker のデフォルトの書式で使用します。 日付の形式の構文は rendered_value で参照できます。ヘルプセンターの記事「Liquid で日付を簡単に書式設定」をご覧ください。[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 つの文字列を返します。この例では「& Pertaptly, Inc"」です。 | A H LI | 8521935 |
Links | |||
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 (たとえば、ユーザー属性が ®ion [リージョン] である場合) 別の例については、動的スキーマとテーブル名挿入のユーザー属性の使用に関するヘルプセンター記事をご覧ください。 |
_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変数の参照形式を適切に選択することが重要です。
何らかの要素がクエリに含まれているかどうかを判別し、それに基づいて特定のテキストを挿入する場合は、次のようなパターンを使用する必要があります。
{% dynamic if view_name.field_name._in_query %}
something to insert if true
{% dynamic else %}
something to insert if false
{% dynamic 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
を使用します。例:
{% dynamic if value == 'Yes' %}
Liquid変数での論理演算子の使用
Liquid 変数には論理演算子 and
、or
、not
を使用できます。Liquid の論理演算子では大文字と小文字が区別され、すべて小文字で記述する必要があります。例:
{% dynamic if value == "Shirt" or value == "Shoes" %}
This is a shirt or shoes.
{% dynamic endif %}
「変数が見つからない」というエラーを取得する
Liquid でこのエラーが表示される理由の 1 つは、次のように {{ }}
と {% %}
を同時に使用している場合です。
{% if value > {{ search_latency_top_hr.limit_95._value }} %}
代わりに、次のようにします。
{% dynamic 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:
{% dynamic if value > 10 %}
<font color="darkgreen">{{ rendered_value }}</font>
{% elsif value > 11 %}
<font color="goldenrod">{{ rendered_value }}</font>
{% dynamic else %}
<font color="darkred">{{ rendered_value }}</font>
{% dynamic 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:
{% dynamic if value > 10 %}
<font color="darkgreen">{{ id._rendered_value }}</font>
{% elsif value > 11 %}
<font color="goldenrod">{{ id._rendered_value }}</font>
{% dynamic else %}
<font color="darkred">{{ id._rendered_value }}</font>
{% dynamic 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
{% dynamic if users_sql_based_dt.city._is_filtered %}
WHERE
users.city = {{ _filters['users_sql_based_dt.city'] | sql_quote }}
{% dynamic 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
メジャーを使用してクエリを生成すると、次の結果が得られます。
この場合、クエリは月ごとに 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
メジャーを使用してクエリを生成すると、次の結果が得られます。
この例では、クエリ内の各月ごとの数ではなく、各月のカウントと各ステータスの数を受信しています。これは、生成された 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: "{% dynamic if row['view_name.field_name'] %} some_label {% dynamic endif %}"
url: "https://www.google.com/search?q={{ row['view_name.field_name'] }}"
}
この構文を使用する場合、link
パラメータは、フィールドが他の方法で選択されているか、クエリに含まれている場合にのみ機能します。
つまり、row[]
構文を使用しても、そのフィールドは {{ field_name._value }}
のようにクエリに追加されません。この項目にユーザーがアクセスできない場合、ダイナミック ラベルはリンクにラベルを付加しないため、リンクメニューからリンクが削除されます。