User Guide Getting Started Help Center Documentation Community Training
New LookML
Old LookML
New LookML
Looker
Liquid Variable Reference

“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 several places in LookML that you can use Liquid:

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: 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, and you must include a space after the opening {{ and before the closing }}. For example: {{ my_liquid_variable }}
  2. Tag Syntax: This type of usage usually doesn’t insert text, it is for logical comparisons and other Liquid operations. In this method, you enclose the Liquid variable in one curly brace and one percent sign, and you must include a space after the opening {% and before the closing %}. For example: {% my_liquid_variable %}

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" /> ;; }

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 ;; 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. The syntax uses an if, else if (denoted as elsif), else structure to check and react to the fields included in the query.

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 ;; }

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:

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> ;; }

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. Can refer to a pivoted field’s value. A H LI 8521935
rendered_value The value of the field with Looker’s default formatting. A H LI $8,521,935.00
filterable_value The value of the field formatted for use as a filter in a Looker URL. A H LI 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 $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
_user_attributes['name_of_attribute'] 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 The time zone in which the query was run. A H LA LI S America/Los_Angeles
_filters['view_name.field_name'] The user filters applied to the field you ask for with view_name.field_name. A H LA LI 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 documentation for examples.
{% parameter parameter_name %} The value of the parameter filter you ask for with parameter_name. LA S See the parameter documentation page for examples.
parameter_name._parameter_value Injects the value of the parameter filter you ask for with parameter_name into a logical statement. H LA LI S See the parameter documentation page for important details and examples.
view_name._in_query Returns true if any field from the view is included in the query. LA S true
view_name.field_name._in_query 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. LA S true
view_name.field_name._is_selected Returns true if the field you ask for with view_name.field_name appears in the query data table. LA S true
view_name.field_name._is_filtered Returns true if the field you ask for with view_name.field_name is included in a filter for the query. 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 the Using date_start and date_end 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 Community topic 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 group_label parameter or with 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 subparameter.

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' %}

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:

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

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.

Top