Liquid Variable Reference

LookML
Version

On this Page
Docs Menu

New in release 5.2 is the ability to use Liquid variables with a field’s label parameter.

“Liquid” is a templating language that you can use in Looker to create more dynamic content. For example, you could build URLs to external tools based on the results of a query, or change which database table is queried based on a user’s selection.

Liquid statements are built from variables, filters, and tags. Variables contain information that you want to use, and the variables that Looker provides are described below. You can further modify those values by using filters and tags, which you can read about in this Liquid guide.

There are five places in LookML that you can use Liquid:

  • The action parameter
  • The html parameter
  • The label parameter of a field
  • The link parameter
  • Parameters that begin with sql (such as sql and sql_on)

Using Liquid Variables

Basic usage of Liquid variables is straightforward. Once you’ve identified the variable you’d like to use (all listed below), simply insert it into a valid LookML parameter. The specific Liquid variables that you can use in specific LookML parameters are defined below.

Two Kinds of Liquid Usage

There are two ways to make use of a Liquid variable:

  1. Output Syntax - In this method, you enclose the Liquid variable in two curly braces, such as {{ my_liquid_variable }}. This type of usage can insert text, and is probably the most common way to use Liquid in Looker.
  2. Tag Syntax - In this method, you enclose the Liquid variable in one curly brace and one percent sign, such as {% my_liquid_variable %}. This type of usage usually doesn’t insert text, it is for logical comparisons and other Liquid operations.

Basic Examples

In this example of HTML usage, a product ID is being inserted into an <img> tag to generate product images:

- dimension: product_image sql: ${product_id} html: | <img src="http://www.acme.com/product_images/{{ value }}.jpg" />
dimension: product_image { sql: ${product_id} ;; html: <img src="http://www.acme.com/product_images/{{ value }}.jpg" /> ;; }

In this example of URL usage, an artist name is being inserted into a URL to produce a Google search for that artist:

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

In this example of SQL usage, the database table is being determined according to which fields the user chooses:

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

In this example of label usage, the email dimension changes its label value depending on the LookML model name. This will dynamically change the name of the field in the field picker and in any query results that include the email dimension:

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

For additional usage examples, see the individual LookML parameter page you’re interested in.

Accessing Variables from Other Fields

Liquid variables are usually based on the field where they are being used. However, you can also access values from other fields if needed.

Use the format {{ view_name.field_name._liquid-variable-name }} to access other fields from the same row in the query result. Replace _liquid-variable-name with any of the Looker Liquid variables. Make sure the variable name is preceded by an underscore if it isn’t normally, like these:

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

This example shows this type of usage to access a website URL from a different field:

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

Liquid Variable Definitions

The following table describes the Liquid variables you can use with LookML. The Usage column indicates which LookML parameters each Liquid variable can be used with, and includes the following options:

A = Works with the action parameter
H = Works with the html parameter
LA = Works with a field’s label parameter
LI = Works with the link parameter
S = Works with all LookML parameters that begin with sql (e.g. sql, sql_on, and sql_table_name)

Variable Definition Usage Example Output
value The raw value of the field returned by the database query

5.0+: Can refer to a pivoted field’s value
A H LI S 8521935
rendered_value The value of the field with Looker’s default formatting A H LI S $8,521,935.00
filterable_value The value of the field formatted for use as a filter in a Looker URL A H LI S 8521935
link The URL to Looker’s default drill link. Note that some fields will not have any default link. A H LI S /explore/thelook/orders?fields=orders.order_amount&limit=500
linked_value The value of the field with Looker’s default formatting and default linking A H LI S $8,521,935.00
_model._name The name of the model for this field A H LA LI S thelook
_view._name The name of the view for this field A H LA LI S orders
_explore._name The name of the explore for this field A H LA LI S order_items
_field._name The name of the field itself A H LA LI S total_order_amount
_dialect._name The SQL dialect being used A H LA LI S mysql
_access_filters['name_of_filter_field'] The value of the access_filter_field you ask for with name_of_filter_field, for the particular user running the query, if access filter fields are being used A H LI S acme
(if, for example, the access filter field was “company”)
_user_attributes['name_of_attribute'] ADDED4.10 The value of the user attribute you ask for with name_of_attribute, for the particular user running the query, if user attributes are being used A H LA LI S northeast
(if, for example, the user attribute was “region”)
_query._query_timezone ADDED4.10 The time zone in which the query was run A H LA LI S America/Los_Angeles
_filters['view_name.field_name'] ADDED4.18 The filters applied to the field you ask for with view_name.field_name. Note that _filters[] will not work with LookML parameters that begin with sql. H L A L NOT NULL
{% date_start date_filter_name %} The beginning date in a date filter you ask for with date_filter_name S 2017-01-01
{% date_end date_filter_name %} The ending date in a date filter you ask for with date_filter_name S 2017-01-01
{% condition filter_name %}
sql_or_lookml_reference
{% endcondition %}
The value of the filter you ask for with filter_name applied to the sql_or_lookml_reference as SQL. This variable is used with Templated Filters and conditional joins. S See the Templated Filters and conditional joins pages for examples
{% parameter parameter_name %} ADDED4.22 The value of the parameter filter you ask for with parameter_name LA S See the parameter page for examples
view_name.field_name._in_query ADDED4.18 Returns true if the field you ask for with view_name.field_name appears in the query data table, or is included in a filter for a query, or is included in a query via the required_fields parameter. Note that _in_query will also work with a field’s label parameter. LA S true
view_name.field_name._is_selected ADDED4.18 Returns true if the field you ask for with view_name.field_name appears in the query data table. Note that _is_selected will also work with a field’s label parameter. LA S true
view_name.field_name._is_filtered ADDED4.18 Returns true if the field you ask for with view_name.field_name is included in a filter for the query. Note that _is_filtered will also work with a field’s label parameter. LA S true

Usage of date_start and date_end

The date_start and date_end Liquid variables are very useful for database dialects that partition data into multiple tables by date, such as BigQuery. Please note that you must use the tag syntax ({% date_start date_filter_name %}) as opposed to the output syntax ({{ date_start date_filter_name }}) even though they do result in text.

See this Discourse article for an in-depth explanation on how to use the date_start and date_end Liquid variables to deal with date partitioned tables.

See this Discourse article for an example of using date_start and date_end for flexible period-over-period analysis.

Usage of _in_query, _is_selected, and _is_filtered

Note that the _in_query, _is_selected, and _is_filtered variables provide either a true or false value, as shown in this example. Consequently, choosing the proper type of Liquid variable reference is important.

If you want to determine whether or not something is included in your query, then insert certain text based on that, you should use a pattern like this:

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

If you want to literally insert the word “true” or “false”, use a pattern like this:

{{ view_name.field_name._in_query }}

Some SQL dialects do not support the literal words “true” and “false”. In that case, you can add the sql_boolean filter to get the true and false values you need:

{{ view_name.field_name._in_query | sql_boolean }}

The same patterns apply to the _is_selected and _is_filtered variables.

Usage of Liquid Variables with the label Parameter

You can use Liquid variables to dynamically change the appearance of a field in the field picker and in visualizations using Liquid variables in a field’s label parameter. See the table above to see which Liquid variables will work with the label parameter.

Liquid variables work only with the label parameter at the field level. They will not work with the label parameter at the model, explore, or view level.

Liquid variables that return a value based on a filter, such as _filters, or require that a query be run before the variable value can be determined, such as in_query, will not change the name of the field in the field picker. In those cases, the field name will only be changed in the resulting visualization.

Note also that when using the parameter Liquid variable with label, the label is passed the value of the value sub-parameter.

Common Challenges

Referencing yesno Fields

To reference a yesno field’s value, the value is case sensitive. Use Yes or No. For example:

{% if value == 'Yes' %}

Getting the “Variable not found” Error

One reason you might get this error in Liquid is if you use {{ }} and {% %} at the same time, like this:

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

Instead do this:

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

If you are using a templated filter, then check whether you are referencing a table name that you have not joined into the derived table.

Still have questions?
Go to Discourse - or - Email Support
Top