请注意，您正在查看 Looker 文档。如需查看 Looker Studio 文档，请访问 https://support.google.com/looker-studio。

液体变量参考

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

Liquid 语句是基于变量、过滤条件和标记构建的。变量包含您要使用的信息，并且 Looker 提供的变量将在本文中进行介绍。您可以使用过滤条件和标记进一步修改这些值，请参阅液体指南。

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

action 参数
字段（但不是探索）的 description 参数
html 参数
字段级别的标签参数，包括 label 参数、view_label 参数、group_label 参数和 group_item_label 参数
link 参数
以 sql 开头的参数（例如 sql 和 sql_on）
default_value 信息中心过滤条件参数
filters 信息中心元素参数

使用 Liquid 变量

Liquid 变量的基本用法很简单。确定要使用的变量后（参见下面的列表），只需将该变量插入有效的 LookML 参数即可。接下来，您可以在特定 LookML 参数中使用特定的 Liquid 变量。

两种液体用法

使用 Liquid 变量的方法有两种：

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

基本示例

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

dimension: product_image {
  sql: ${product_id} ;;
  html: <img src="https://www.altostrat.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，否则 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 }} Liquid 变量语法引用另一个字段时，所引用的字段会添加到 SQL 查询的 SELECT 子句中，并作为附加列添加到 GROUP BY 子句中。这是正确检索引用字段中的值的必要条件。但是，汇总测量结果会导致意外结果。有关详情，请参阅本页面中在汇总衡量中使用 Liquid 变量部分。

液体变量定义

下表介绍了可与 LookML 搭配使用的 Liquid 变量。用量列指明每个 Liquid 变量可以与哪些 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` 中引用日期格式语法，如通过 Liquid 轻松设置日期格式最佳做法页面所示。除了用量列中显示的参数外，`action` 和 `link` 参数的 `label` 子参数也支持 `rendered_value`。	A H LI	8521935.00 美元
`filterable_value`	字段格式的值，用作 Looker 网址中的过滤条件。例如，在过滤包含逗号的字符串值（例如“Altostrat, Inc”）时，`value` 变量会返回两个不同的字符串：“Altostrat”和“Inc”。`filterable_value` 变量通过转义特殊字符并返回单个字符串（在本例中为“Altostrat, 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_or_lookml_reference` 的 SQL。此变量与模板化过滤器和条件联接配合使用。	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 （例如，如果用户属性是“region”）如需查看其他示例，请参阅将用户属性用于动态架构和表名称注入最佳实践页面。
`_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 Liquid 变量对于按日期将数据拆分到多个表的数据库方言非常有用，例如 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”上的“探索”，“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 最佳做法页面，深入了解如何使用 date_start 和 date_end Liquid 变量处理日期分区表。

如需查看使用 date_start 和 date_end 进行灵活时间段分析的示例，请参阅“分析禁播的灵活时间段对比分析”社区帖子。

使用 `_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 参数中使用 Liquid 变量来动态更改字段在字段选择器和可视化图表中的外观。请参阅本页的表部分，了解哪些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 的其他 Liquid 变量（例如基于过滤条件返回值的变量（例如 _filters）或要求在确定变量值之前运行的查询）（例如 in_query）不会更改字段选择器中的字段名称。在这种情况下，系统只会在最终可视化图表中更改字段名称。

将 parameter Liquid 变量与 label 搭配使用时，系统会向 label 传递 value 子参数的值。

将流动变量与 `description` 参数搭配使用

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

流动变量仅在字段级别使用 description 参数。它们无法与探索级别的 description 参数搭配使用。

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

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

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

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

注意事项

引用 `yesno` 字段

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

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

将逻辑运算符与 Liquid 变量一起使用

您可以将逻辑运算符 and、or 和 not 与 Liquid 变量一起使用。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'] Liquid 变量，其中的值以 SQL 形式呈现且过滤器返回字符串值，则需要在输出周围添加英文单引号。为此，您可以添加 sql_quote 液体过滤器。

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

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

或

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

您可以将 Liquid 过滤条件 | sql_quote 附加到 Liquid 变量声明：

{{ _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 Liquid 过滤条件，以确保输出 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') 两边的引号。

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

当您使用某个测量的 {{ view_name.field_name._value }} 语法或 link 或 html 参数中的 {{ 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 with With 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 测量值生成查询时，您会获得以下结果：

选择“Createed 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

为阻止这种情况发生，可以将 row[] 函数与 Liquid 变量一起使用，该函数会从浏览器中呈现的结果中提取值，因此不会将引用的字段添加到 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 }} 中那样将字段添加到查询中。如果该字段不可用，动态标签会导致链接没有标签，从而导致链接在链接菜单中消失。