Liquid Variable Reference

LookML
Version

On this Page
Docs Menu
  • Explore
  • Develop
  • Administer
  • Setup
  • “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 three places in LookML that you can use Liquid:

    • In HTML, for example in the html parameter
    • In URLs, for example in the link parameter
    • In SQL, for example in the sql parameter

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

    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 Variables for HTML, URLs, and SQL

    The following Liquid variables can be used in the html, link, and action LookML parameters.

    Variable Definition Example Output
    value The raw value of the field returned by the database query 8521935
    rendered_value The value of the field with Looker’s default formatting $8,521,935.00
    filterable_value The value of the field formatted for use as a filter in a Looker URL 8521935
    link The URL to Looker’s default drill link. Note that some fields will not have any default link. /explore/thelook/orders?fields=orders.order_amount&limit=500
    linked_value The value of the field with Looker’s default formatting and default linking $8,521,935.00
    _model._name The name of the model for this field thelook
    _view._name The name of the view for this field orders
    _explore._name The name of the explore for this field order_items
    _field._name The name of the field itself total_order_amount
    _dialect._name The SQL dialect being used 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 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 northeast
    (if, for example, the user attribute was “region”)
    _query._query_timezone ADDED4.10 The time zone in which the query was run 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. NOT NULL

    Liquid Variables for SQL Only

    You can also use Liquid variables with all LookML parameters that begin with sql. Common examples are the sql, sql_on, and sql_table_name parameters.

    Variable Definition Example Output
    {% date_start date_filter_name %} The beginning date in a date filter you ask for with date_filter_name 2017-01-01
    {% date_end date_filter_name %} The ending date in a date filter you ask for with date_filter_name 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. See the Templated Filters and conditional joins pages 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 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 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 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
    

    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.

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