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

Liquid 变量参考文档

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 操作。在此方法中，您需要将 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 子句中。这是正确检索引用字段中的值所必需的。不过，汇总指标可能会导致意外结果。如需了解详情，请参阅本页面上的在汇总测量中使用液体变量部分。

液体变量定义

下表介绍了可与 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	8,521,935.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	8,521,935.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 S	/dashboards/5
`_field._name`	字段本身的名称，采用 `view_name.field_name` 格式。	A DE H LA LI S	order.total_order_amount [订单总额]
查询
`_query._query_timezone`	运行查询的时区。	A DE H LA LI S	America/Los_Angeles
`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`

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 日这一日期范围过滤“探索”，那么 filter_start 维度的评估结果将为 2022 年 4 月 1 日；filter_end 维度的评估结果为 2022 年 5 月 25 日。new_filter_test

对于 date_start 和 date_end，请注意以下事项：

如果用户未使用 Liquid 变量的 date_filter 部分中指定的过滤条件来过滤查询，则 {% date_start date_filter %} 和 {% date_end date_filter %} 的求值结果都为 NULL。
如果用户利用对 Liquid 变量 date_filter 部分中指定的过滤条件进行过滤的自由范围来过滤查询，则范围的开放端将解析为 NULL。例如，使用示例，如果在“探索”中，用户将 new_filter_test 设置为 2022-06-07 之前，则 {% date_start date_filter %} 输出将为 NULL，因为用户指定的范围包含结束日期，但没有开始日期。如果用户将 new_filter_test 设置为 2022-06-07 之后，则 {% date_end date_filter %} 输出将为 NULL。

在以下任一情况下，液态输出可能会显示 NULL 结果，请务必在 sql 参数中添加 SQL 函数以考虑 NULL 值（例如 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 变量来动态更改字段在字段选择器和可视化图表中的外观。请参阅此页面上的表格部分，了解哪些 Liquid 变量适用于 label 参数。

Liquid 变量适用于字段级的标签参数，包括 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 参数。

Liquid 变量仅在字段级别使用 description 参数。它们无法在“探索”级别使用 description 参数。

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

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

上述表中标有 DE 的其他液体变量（例如根据过滤器返回值的流动变量（如 _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 参数中使用以下任一 Liquid 变量：

{{ _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 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 衡量生成查询后，您会获得以下结果：

结果中选择的是“已创建月份”和“无液体计数”字段的数据表。

在这种情况下，该查询每个月都会返回一个计数。针对先前结果生成的 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

若要阻止发生这种情况，可以选择将 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 }} 一样添加到查询中。如果该字段不可用，动态标签将导致链接没有标签，从而导致链接在链接菜单中消失。