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 on this page. You can further modify those values by using filters and tags, which you can read about in this Liquid guide.

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

• The action parameter
• The description parameter of a field (but not of an Explore)
• The html parameter
• Label parameters at the field level, including the label parameter, view_label parameter, group_label parameter, and group_item_label parameter
• The link parameter
• Parameters that begin with sql (such as sql and sql_on)
• The default_value dashboard filter parameter
• The filters dashboard element parameter

Using Liquid variables

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

Two kinds of Liquid usage

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

1. Output Syntax: This type of usage can insert text, and is probably the most common way to use Liquid in Looker. In this method, you enclose the Liquid variable in two curly braces. For example: {{ value }}
2. Tag Syntax: This type of usage usually doesn’t insert text; instead, it is for logical comparisons and other Liquid operations. In this method, you enclose the Liquid variable in one curly brace and a single percent sign. For example: {% if value > 10000 %}

Basic examples

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

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

In this example of SQL usage, the database table is being determined according to which fields the user chooses. The syntax uses an if, else if (denoted as elsif), else structure to check and react to the fields included in the query.

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:

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:

When you reference another field using the {{ field_name._value }} Liquid variable syntax, the referenced field is added to the SELECT clause of the SQL query and added as an additional column in the GROUP BY clause. This is necessary to properly retrieve the values in the referenced field. But it can cause unexpected results in aggregate measures. For more information, see the Using Liquid variables in aggregate measures Help Center article.

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
dv = Works with the default_value (for dashboards) parameter
de = Works with the description parameter at the field level, but will not work with description at the Explore level
f = Works with the filters (for dashboard elements) parameter
h = Works with the html parameter
la = Works with the label parameters at the field level, including the label parameter, view_label parameter, group_label parameter, and group_item_label parameter, but will not work with label parameters at the model, Explore, view, or reference line level, or with label as a subparameter of link
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)

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 the Using date_start and date_end Looker Community topic for an in-depth explanation on how to use the date_start and date_end Liquid variables to deal with date-partitioned tables.

See the Analytic Block Flexible period-over-period analysis Help Center 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 you want to literally insert the word “true” or “false”, use a pattern like this:

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:

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 in a field’s label parameter to dynamically change the field’s appearance in the field picker and in visualizations. See the table section on this page to see which Liquid variables will work with the label parameter.

Liquid variables work with label parameters at the field level, including the label parameter, view_label parameter, group_label parameter, and group_item_label parameter, but will not work with label parameters at the model, Explore, view, or reference line level, or with label as a subparameter of link.

The following variables can be used with label to affect the field picker, column headers in the data section of an Explore, and visualizations:

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

The other Liquid variables marked with LA in the table above, such as those that return a value based on a filter (like _filters) or require that a query be run before the variable value can be determined (like 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.

When using the parameter Liquid variable with label, label is passed the value of the value subparameter.

Usage of Liquid variables with the description parameter

You can use Liquid variables with the description parameter to dynamically change the description for a field. This description appears when users hover over the field’s information icon in the field picker, the field’s column name in the data section of the Explore, or the field’s column name in a table chart. See the table in the Liquid variable definitions section on this page to see which Liquid variables work with the description parameter.

Liquid variables work with the description parameter only at the field level. They will not work with the description parameter at the Explore level.

The following variables can be used with description to affect the field picker, the data section of an Explore, and the column header in a table chart:

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

The other Liquid variables marked with DE in the table above, such as Liquid variables that return a value based on a filter (like _filters) or require that a query run before the variable value can be determined (like in_query) will not change the description in the field picker or in the data section of an Explore. These Liquid variables will only affect the description shown when a user hovers over the field’s column header in a table chart.

For examples of how to use Liquid in the description parameter, see the description parameter documentation page.

Things to consider

Referencing yesno fields

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

Using logical operators with Liquid variables

You can use the logical operators and, or, and not with Liquid variables. Logical operators in Liquid are case-sensitive and must be written in all lower-case. For example:

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:

Instead do this:

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.

Naming conventions can affect query grouping

If there is a field with the name value, this field will be included in the GROUP BY clause of an Explore query whenever the value Liquid variable is referenced in another field within the same view.

For example:

This will generate the following SQL when only id is selected in an Explore:

To avoid this grouping behavior, make sure to scope the value variable with the name of the field to explicitly reference the field:

Using _filters['view_name.field_name'] in a derived table requires sql_quote

When you are defining a SQL-based derived table, if you use the _filters['view_name.field_name'] Liquid variable where the value is rendered in SQL and the filter returns a string value, you need to add single quotation marks around the output. You can do this by including the sql_quote Liquid filter.

For example, if you are using either of these Liquid variables in the sql parameter of a derived_table parameter:

or

You can append the Liquid filter | sql_quote to the Liquid variable declaration:

and

Here is an example derived table that uses the _filters['view_name.field_name'] variable:

The city field is a string that will be output to SQL, so the sql_quote Liquid filter is needed to be sure that the output SQL is enclosed in single quotes. In the resultant Explore, when a user specifies a city name as a filter, Looker encloses the city name string in quotes. Looker sends this SQL to the database if a user filters the Explore query on the city value New York:

If you are using the _filters['view_name.field_name'] Liquid variable for a string field in a derived table where the value is rendered in SQL, you will get the following LookML warning if you do not append | sql_quote to the Liquid variable:

Using "_filters[]" in Derived Table SQL without "sql_quote" is discouraged.

You can also use sql_quote with this syntax to quote multiple values in an array:

Here is an example where the Liquid output is being used as input for an IN statement:

With this syntax, the Liquid output will have quotes around each individual value ('value1','value2','value3') instead of having quotes around the full list ('value1, value2, value3').