液体变量参考

Liquid 是一种模板语言，可用于在 Looker 中创建更多动态内容。例如，您可以根据查询结果构建外部工具的网址，或根据用户的选择更改查询哪个数据库表。

液态语句由变量、过滤器和代码组成。变量包含您要使用的信息；本页面介绍了 Looker 提供的变量。您可以使用过滤条件和标记进一步修改这些值，具体请参阅液体指南。

您可以在 LookML 中的多个位置使用 Liquid：

使用液体变量

液体变量的基本用法非常简单。确定要使用的变量后（请参阅以下列表），只需将其插入有效的 LookML 参数中即可。接下来，您可以定义可在特定 LookML 参数中使用的特定液体变量。

两种液体使用情况

您可以通过以下两种方式使用液体变量：

  1. 输出语法：这种用法可以插入文本，并且可能是在 Looker 中使用 Liquid 的最常见方式。在此方法中，您需要将 Liquid 变量括在两个花括号中。例如：{{ value }}
  2. 代码语法：此类用法通常不会插入文本；相反，用于逻辑比较和其他液体操作。在此方法中，您需要将 Liquid 变量括在一对大括号中和一个百分号。例如：{% dynamic if value > 10000 %}

基本示例

在下面的 HTML 用法示例中，商品 ID 会插入 <img> 标记中以生成商品图片：

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

在这个网址使用示例中，将艺术家姓名插入网址中，以便在 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 %} ;;

在此示例中，标签维度 email 维度会根据 LookML 模型名称更改其 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 参数页面。

访问其他字段中的变量

液体变量通常基于使用它们的字段。不过，您也可以根据需要访问其他字段中的值。

使用 {{ view_name.field_name._liquid-variable-name }} 格式可访问查询结果中同一行中的其他字段。将 _liquid-variable-name 替换为任何 Looker 液体变量。确保变量名称前面以下划线开头（如果正常情况下为），如下所示：

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

以下示例展示了从不同字段访问网站网址的用法：

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

当您使用 {{ field_name._value }} 液态变量语法引用另一个字段时，引用的字段会添加到 SQL 查询的 SELECT 子句中，并作为额外的列添加到 GROUP BY 子句中。必须这样做才能正确检索引用字段中的值。不过，这可能会导致汇总衡量结果出现意外结果。如需了解详情，请参阅本页面中在汇总衡量中使用液体变量部分。

液体变量定义

下表介绍了可与 LookML 搭配使用的液体变量。用量列指明每个液体变量可用于哪些 LookML 参数，并包含以下选项：

A = 可与 action 参数配合使用

DV = 可与 default_value（适用于信息中心）参数配合使用

DE = 可在字段级别使用 description 参数，但不适用于探索级别的 description

F = 可与 filters（适用于信息中心元素）参数配合使用

H = 可与 html 参数配合使用

LA = 可以在字段级别使用标签参数，包括 label 参数、view_label 参数、group_label 参数和 group_item_label 参数，但不适用于模型、探索、视图或引用行级别的标签参数，或者将 label 作为 link 的子参数

LI = 可与 link 参数配合使用

S = 可与以 sql 开头的所有 LookML 参数（例如，sql、sql_on 和 sql_table_name）搭配使用

变量 定义 用量 输出示例
字段值
value 数据库查询返回的字段的原始值。可以引用透视字段的值。

除了用量列中显示的参数外，action 和 link 参数的 label 子参数也支持 value。		 A H LI 8521935
rendered_value 采用 Looker 默认格式的字段值。

您可以参考 rendered_value 中的日期格式语法一文，详见帮助中心文章帮助中心文章。

除使用情况列中显示的参数外，action 和 link 参数的 rendered_value 子参数也支持 rendered_value。		 A H LI 8,521,935.00 美元
filterable_value 该字段的值的格式，可在 Looker 网址中用作过滤器。

例如，在过滤包含英文逗号的字符串值（例如“Periaptly, Inc”）时，value 变量会返回两个不同的字符串“Periaptly”和“Inc”。filterable_value 变量通过转义特殊字符并返回单个字符串来更正此问题，在此示例中为“Periaptly, Inc”。		 A H LI 8521935
Links
link Looker 的默认细目链接的网址。请注意，有些字段没有任何默认链接。 A H LI S /explore/thelook/orders?fields=orders.order_amount&limit=500
linked_value 具有 Looker 默认格式和默认链接的字段的值。测量值没有默认关联，因此测量指标需要配置 drill_fields 参数才能与 linked_value 配合使用。 A H LI $8521935.00
过滤条件
_filters['view_name.field_name'] 用户过滤条件会应用于您使用 view_name.field_name 请求的字段。

派生表的 sql 参数也支持 _filters['view_name.field_name']，但其他 sql 参数也不支持。

在派生表 sql 参数中使用 _filters['view_name.field_name'] 需要 sql_quote 液体过滤器。		 A DE H LA LI 非空
{% 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['name_of_attribute'] 使用 name_of_attribute 请求的用户属性的值，适用于使用查询的特定用户（如果使用了用户属性）。_user_attributes['name_of_attribute'] 变量也可以在高级过滤条件语法中使用。 A DE H LA LI S DV F northeast
（例如，用户属性为“地区”）

如需查看其他示例，请参阅帮助中心文章：使用用户属性实现动态架构和表名称注入。
_localization['localization_key'] 根据模型的语言区域，返回与模型字符串文件中定义的本地化键相关联的值。 DV F 如需查看示例，请参阅将 LookML 模型本地化文档页面。
LookML 对象
_model._name 此字段的模型名称。 A DE H LA LI S 外观
_view._name 此字段的视图名称。 A DE H LA LI S 订单
_explore._name “探索”字段的名称。 A DE H LA LI S order_items [订单商品]
_explore._dashboard_url ADDED 22.12 当前信息中心的相对网址。H LI /dashboards/5
_field._name 字段本身的名称，采用 view_name.field_name 格式。 A DE H LA LI S orders.total_order_amount
查询
_query._query_timezone 运行查询的时区。 A DE H LA LI S America/Los_Angeles
view_name._in_query 如果查询中包含视图的任何字段，则返回 true。 DE LA LI S 是
view_name.field_name._in_query 如果您使用 view_name.field_name 请求的字段出现在查询数据表中、包含在查询的过滤条件中或通过 required_fields 参数包含在查询中，则返回 true。 DE LA LI S 是
view_name.field_name._is_selected 如果您要求 view_name.field_name 的字段出现在查询数据表中，则返回 true。 DE LA LI S 是
view_name.field_name._is_filtered 使用 view_name.field_name 请求的字段包含在查询的过滤条件中时，会返回 true。 DE LA LI S 是

date_start 和 date_end 的使用

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 日这一日期范围过滤“探索”专区，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，因为用户指定的范围包含结束日期，但没有开始日期。如果用户将 new_filter_test 设置为 2022-06-07 之后，则 {% date_end date_filter %} 输出将为 NULL。

在这两种情况下，液体输出可能会显示 NULL 的结果，因此请务必根据 SQL 参数在 sql 参数中添加一个 SQL 函数，例如 IFNULL 或 COALESCE。

请参阅使用 date_start 和 date_end Looker 社区主题，深入了解如何使用 date_start 和 date_end 液体变量处理日期分区表。

有关使用 date_start 和 date_end 进行灵活时间段分析的示例，请参阅 Google Analytics（分析）中关于时间段的灵活分析一文。

使用了 _in_query、_is_selected 和 _is_filtered

请注意，_in_query、_is_selected 和 _is_filtered 变量提供 true 或 false 值，如此示例所示。因此，选择适当的液体变量类型非常重要。

如果要确定查询中是否包含某段内容，然后基于此插入某些文本，则应使用如下格式：

{% 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 参数

您可以在字段的 label 参数中使用液体变量来动态更改字段在字段选择器和可视化图表中的外观。请参阅此页面上的表部分，了解哪些变量适用于 label 参数。

液体变量可在字段级别使用标签参数，包括 label 参数、view_label 参数、group_label 参数和 group_item_label 参数，但不适用于模型、探索、视图或参考线级别的标签参数，或者将标签用作 link 的子参数。

以下变量可与 label 结合使用，以影响字段选择器、“探索”数据部分中的列标题以及可视化图表：

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

上表中标有 LA 的其他液态变量（例如根据过滤条件返回值的类似变量，例如 _filters）或要求在确定变量值之前运行查询的变量（如 in_query）不会更改字段选择器中的字段名称。在这些情况下，字段名称只会在更改后的图表中进行更改。

将 parameter 液体变量与 label 结合使用时，系统会向 label 传递 value 子参数的值。

搭配使用液体变量和 description 参数

您可以将液体变量与 description 参数结合使用，以动态更改字段的说明。当用户将鼠标悬停在字段选择器中的字段信息图标、“探索”数据部分的字段列名称或表格图表中的字段列名称上时，就会显示此说明。请参阅本页面液体变量定义部分中的表格，了解哪些description变量可用于液体变量。

液体变量只能在字段级别使用 description 参数。它们在“探索”级别不支持 description 参数。

以下变量可与 description 配合使用，以影响字段选择器、“探索”功能的数据部分以及表格图表中的列标题：

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

上图中标有 DE 的其他液态变量（例如根据过滤条件返回值的液体变量（如 _filters）或要求在确定变量值之前运行查询）不会更改“字段选择器”或“探索”数据部分的说明。只有当用户将鼠标悬停在表格图表中的字段列标题上时，这些液体变量才会影响显示的说明。

如需查看有关如何在 description 参数中使用 Liquid 的示例，请参阅 description 参数文档页面。

注意事项

引用 yesno 字段

如需引用 yesno 字段的值，该值区分大小写。使用 Yes 或 No。例如：

{% dynamic if value == 'Yes' %}

对逻辑变量使用逻辑运算符

您可以将逻辑运算符 and、or 和 not 用于液体变量。Liquid 中的逻辑运算符区分大小写，且必须全部小写。例如：

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

发生“找不到变量”错误

如果您在 Liquid 中遇到此错误，一个原因是您同时使用 {{ }} 和 {% %}，如下所示： 

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

正确的做法是： 

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

如果使用模板化过滤条件，请检查引用的引用是否尚未联接到派生表。

命名规范可能会影响查询分组

如果存在名为 value 的字段，每当 value 液体变量引用了同一视图中的其他字段时，该字段都会包含在“探索”查询的 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
}

当“探索”中只选择 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 的派生表时，如果您使用 _filters['view_name.field_name'] 液体变量（其中的值以 SQL 形式呈现并且过滤器返回字符串值），则需要在输出内容前后添加单引号。为此，您可以添加 sql_quote 液体过滤器。

例如，如果您在 derived_table 参数的 sql 参数中使用以下任一液体变量：

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

或

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

您可以将液体过滤器 | 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_quote 液体过滤条件以确保输出 SQL 用单引号括起来。在生成的“探索”中，当用户将城市名称指定为过滤条件时，Looker 会将城市名称字符串用引号括起来。如果用户对城市值 New York 进行过滤“探索”查询，Looker 会将此 SQL 发送到数据库：

WHERE
    users.city = 'New York'

如果您在派生表中以 SQL 形式呈现的字符串字段使用 _filters['view_name.field_name'] Liquid 变量，且未将 | sql_quote 附加到 Liquid 变量，您会收到以下 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(",") }})

使用此语法，液体输出将对每个值 ('value1','value2','value3') 加引号，而不是用整个列表 ('value1, value2, value3') 加引号。

汇总指标中的液体变量会影响分组

当您使用测量结果的 link 或 html 参数中的 {{ view_name.field_name._value }} 语法或 {{ field_name._value }} 语法引用其他字段中的值时，Looker 会将该字段提取到 SQL 查询中以获取字段值。因此，Liquid 可能会影响 SQL 查询的生成方式以及 GROUP BY 子句使用的列数，这可能会导致您在使用汇总指标（例如 type: count 的衡量指标）时发生意外行为。

例如，假设您有以下两项措施：

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”和“Count Without Liquid”字段的查询。

在这种情况下，查询每月返回一个计数。接下来为之前的结果生成的 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: "{% 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 }} 一样添加到查询中。如果该字段不可用，动态标签会导致链接没有标签，导致链接在链接菜单中消失。