Líquido é uma linguagem de modelo que você pode usar no Looker para criar conteúdo mais dinâmico. Por exemplo, é possível criar URLs para ferramentas externas com base nos resultados de uma consulta ou alterar a tabela do banco de dados consultada com base na seleção de um usuário.
As instruções líquidas são criadas a partir de variáveis, filtros e tags. As variáveis contêm informações que você quer usar e as variáveis fornecidas pelo Looker são descritas nesta página. É possível modificar ainda mais esses valores usando filtros e tags. Leia mais neste guia de líquidos.
É possível usar o Liquid em vários lugares no LookML:
- Parâmetro
action - O parâmetro
descriptionde um campo, mas não de um recurso Explorar. - Parâmetro
html - Parâmetros de rótulo no nível do campo, incluindo
label,view_label,group_labelegroup_item_label - Parâmetro
link - Parâmetros que começam com
sql(comosqlesql_on) - Parâmetro de filtro do painel
default_value - Parâmetro do elemento do painel
filters
Como usar variáveis líquidas
O uso básico de variáveis líquidas é simples. Depois de identificar a variável que você quer usar (veja a lista a seguir), basta inseri-la em um parâmetro LookML válido. As variáveis Liquid específicas que você pode usar em parâmetros LookML específicos são definidas a seguir.
Dois tipos de uso líquido
Há duas maneiras de usar uma variável líquida:
- Sintaxe de saída: esse tipo de uso pode inserir texto e provavelmente é a forma mais comum de usar o Liquid no Looker. Nesse método, a variável Liquid é colocada entre duas chaves. Por exemplo:
{{ value }} - Sintaxe da tag: esse tipo de uso não insere texto. Ele é usado para comparações lógicas e outras operações de líquidos. Nesse método, você coloca a variável Liquid em uma chave e um sinal de porcentagem. Por exemplo:
{% dynamic if value > 10000 %}
Exemplos básicos
Neste exemplo de uso do HTML, um ID do produto está sendo inserido em uma tag <img> para gerar imagens do produto:
dimension: product_image {
sql: ${product_id} ;;
html: <img src="https://www.altostrat.com/product_images/{{ value }}.jpg" /> ;;
}
Neste exemplo de uso do URL, o nome de um artista é inserido em um URL para produzir uma pesquisa do Google sobre esse artista.
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"
}
}
Neste exemplo de uso do SQL, a tabela do banco de dados está sendo determinada de acordo com os campos que o usuário escolher. A sintaxe usa uma estrutura if, ou se (representada como elsif), else para verificar e reagir aos campos incluídos na consulta.
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 %} ;;
Neste exemplo de uso do rótulo, a dimensão email muda o valor label, dependendo do nome do modelo LookML. Isso muda dinamicamente o nome do campo no seletor de campo e em qualquer resultado de consulta que inclua a dimensão 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 ;;
}
Para outros exemplos de uso, consulte a página individual do parâmetro LookML em que você tem interesse.
Como acessar variáveis de outros campos
As variáveis líquidas geralmente se baseiam no campo em que estão sendo usadas. No entanto, você também pode acessar valores de outros campos, se necessário.
Use o formato {{ view_name.field_name._liquid-variable-name }} para acessar outros campos na mesma linha no resultado da consulta. Substitua _liquid-variable-name por qualquer uma das variáveis Liquid do Looker. Verifique se o nome da variável é precedido por um sublinhado, se não for normal, como este:
{{ view_name.field_name._value }}{{ view_name.field_name._rendered_value }}{{ view_name.field_name._model._name }}
Este exemplo mostra este tipo de uso para acessar o URL de um site em um campo diferente:
dimension: linked_name {
sql: ${name} ;;
html: <a href="{{ website.url._value }}" target="_blank">{{ value }}</a> ;;
}
Quando você faz referência a outro campo com a sintaxe de variável líquida
{{ field_name._value }}, o campo referenciado é adicionado à cláusulaSELECTda consulta SQL e incluído como uma coluna adicional na cláusulaGROUP BY. Isso é necessário para recuperar corretamente os valores no campo referenciado. No entanto, isso pode gerar resultados inesperados em medidas agregadas. Para mais informações, consulte a seção sobre como usar variáveis líquidas em medidas agregadas nesta página.
Definições de variáveis líquidas
A tabela a seguir descreve as variáveis Liquid que podem ser usadas com o LookML. A coluna Uso indica com quais parâmetros LookML cada variável Liquid pode ser usada e inclui as seguintes opções:
A = Funciona com o parâmetro action.
DV = Funciona com o parâmetro default_value (para painéis).
DE = Funciona com o parâmetro description no campo, mas não funciona com description no nível Explorar.
F = Funciona com o parâmetro filters (para elementos do painel).
H = Funciona com o parâmetro html.
LA = Funciona com os parâmetros de rótulo no nível do campo, incluindo os parâmetros label, view_label, group_label e group_item_label, mas não funciona com parâmetros de rótulo no nível de modelo, Explorar, visualização ou referência, ou com label como um subparâmetro de link.
LI = Funciona com o parâmetro link.
S = Funciona com todos os parâmetros LookML que começam com sql (por exemplo, sql, sql_on e sql_table_name).
| Variável | Definição | Uso | Exemplo de saída |
|---|---|---|---|
| Valores de campo | |||
value | Valor bruto do campo retornado pela consulta do banco de dados. Pode se referir a um valor dinâmico de campo. Além dos parâmetros exibidos na coluna Uso, value é aceito no subparâmetro label dos parâmetros action e link. | A H LI | 8521935 |
rendered_value | O valor do campo com a formatação padrão do Looker. Você pode fazer referência à sintaxe de formatação de data em rendered_value, conforme mostrado na página de práticas recomendadas de Práticas recomendadas para líquidos.Além dos parâmetros exibidos na coluna Uso, rendered_value é aceito no subparâmetro label dos parâmetros action e link. | A H LI | US$ 8.521.935,00 |
filterable_value | O valor do campo formatado para uso como filtro em um URL do Looker. Por exemplo, ao filtrar um valor de string que inclui uma vírgula como "Altostrat, Inc", a variável value retorna duas strings diferentes, "Altostrat" e "Inc". A variável filterable_value corrige isso fazendo o escape de caracteres especiais e retornando uma única string, como "Altostrat, Inc". | A H LI | 8521935 |
| Links | |||
link | O URL para o link de detalhamento padrão do Looker. Alguns campos não têm links padrão. | A H LI S | /explore/thelook/orders?fields=orders.order_amount&limit=500 |
linked_value | O valor do campo com formatação e vinculação padrão do Looker. As medidas não têm vinculação padrão. Por isso, é necessário configurar o parâmetro drill_fields para trabalhar com linked_value. | A H LI | US$8.521.935,00 |
| Filtros | |||
_filters['view_name.field_name'] | Os filtros de usuário aplicados ao campo solicitado com view_name.field_name._filters['view_name.field_name'] também é compatível com o parâmetro sql de uma tabela derivada, mas não em outros parâmetros sql. O uso de _filters['view_name.field_name'] em um parâmetro sql da tabela derivada requer o filtro líquido sql_quote. | A DE H LA LI | NÃO NULOS |
{% date_start date_filter_name %} | A data de início em um filtro de data solicitado por date_filter_name. Consulte a seção Uso de date_start e date_end para mais informações. | S | 2017-01-01 |
{% date_end date_filter_name %} | A data de término em um filtro de data solicitado por date_filter_name. Consulte a seção Uso de date_start e date_end para mais informações. | S | 2017-01-01 |
{% condition filter_name %}sql_or_lookml_reference{% endcondition %} | O valor do filtro solicitado com filter_name aplicado ao sql_or_lookml_reference como SQL. Essa variável é usada com filtros baseados em modelo e mesclagens condicionais. | S | Consulte a página de documentação de Filtros com modelo e a seção mesclagens condicionais da página de documentação sql_on para ver exemplos. |
{% parameter parameter_name %} | O valor do filtro de parâmetro solicitado com parameter_name. | DE LA S | Veja exemplos na página de parâmetros do parameter. |
parameter_name._parameter_value | Injeta o valor do filtro de parâmetro que você solicitou com parameter_name em uma instrução lógica. | DE H LA LI S | Consulte a página de documentação do parâmetro parameter para ver detalhes e exemplos importantes. |
| Atributos do usuário | |||
_user_attributes['name_of_attribute'] | O valor do atributo do usuário que você pede com name_of_attribute para o usuário específico que está executando a consulta, se os atributos do usuário estiverem sendo usados. A variável _user_attributes['name_of_attribute'] também pode ser usada na sintaxe do filtro avançado. | A DE H LA LI S DV F | nordeste (se, por exemplo, o atributo do usuário era "região") Consulte a página Como usar atributos do usuário para injeção dinâmica de nomes de esquema e tabela para ver um exemplo adicional. |
_localization['localization_key'] | Retorna o valor associado a uma chave de localização definida no arquivo de strings de um modelo com base na localidade do usuário. | DV F | Consulte a página Como localizar seu modelo do LookML para ver um exemplo. |
| Objetos LookML | |||
_model._name | O nome do modelo para este campo. | A DE H LA LI S | o olhar |
_view._name | O nome da visualização desse campo. | A DE H LA LI S | pedidos |
_explore._name | Nome do campo "Explorar". | A DE H LA LI S | pedido_itens |
_explore._dashboard_url | ADDED 22.12 O URL relativo do painel atual. | H LI | /dashboards/5 |
_field._name | O nome do próprio campo, no formato view_name.field_name. | A DE H LA LI S | pedidos.total_order_amount |
| Consultas | |||
_query._query_timezone | O fuso horário em que a consulta foi executada. | A DE H LA LI S | America/Los_Angeles |
view_name._in_query | Retorna true se algum campo da visualização estiver incluído na consulta. | DE LA LI S | verdadeiro |
view_name.field_name._in_query | Retornará true se o campo solicitado com view_name.field_name aparecer na tabela de dados de consulta, for incluído em um filtro para uma consulta ou estiver incluído em uma consulta por meio do parâmetro required_fields. | DE LA LI S | verdadeiro |
view_name.field_name._is_selected | Retorna true se o campo solicitado com view_name.field_name aparecer na tabela de dados de consulta. | DE LA LI S | verdadeiro |
view_name.field_name._is_filtered | Retornará true se o campo solicitado com view_name.field_name estiver incluído em um filtro para a consulta. | DE LA LI S | verdadeiro |
Uso de date_start e date_end
As variáveis Liquid date_start e date_end são muito úteis para dialetos de banco de dados que particionam dados em várias tabelas por data, como o BigQuery. Use a sintaxe de tags {% date_start date_filter_name %} ou {% date_end date_filter_name %}. Não é possível usar a sintaxe de saída {{ date_start date_filter_name }}{{ date_end date_filter_name }}
Por exemplo, é possível criar esses campos em uma visualização:
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 %} ;;
}
Se você filtrar uma exploração em new_filter_test usando o período de 1o de abril de 2022 a 25 de maio de 2022, a dimensão filter_start será avaliada como 1o de abril de 2022, e a filter_end como 25 de maio de 2022.
Observe o seguinte sobre date_start e date_end:
Se o usuário não filtrar a consulta usando o filtro especificado na parte
date_filterda variável Liquid,{% date_start date_filter %}e{% date_end date_filter %}serão avaliadas como NULL.Se o usuário filtrar a consulta com um intervalo aberto no filtro especificado na parte
date_filterda variável Liquid, o final aberto do intervalo será resolvido como NULL. Por exemplo, usando example, se, em "Explorar", um usuário definir anew_filter_testcomo antes de 2022-06-07, a saída{% date_start date_filter %}será NULL, já que o usuário especificou um intervalo com data de término, mas não data de início. Se um usuário definir onew_filter_testcomo após 2022-06-07, a saída do{% date_end date_filter %}será NULL.
Em qualquer um desses cenários em que a saída do Liquid pode mostrar um resultado NULL, inclua uma função SQL no parâmetro sql para considerar valores NULL, como IFNULL ou COALESCE, dependendo do seu dialeto do banco de dados.
Consulte a página de práticas recomendadas Como usar date_start e date_end para ver uma explicação detalhada sobre como usar as variáveis Liquid date_start e date_end para processar tabelas particionadas por data.
Consulte a postagem da Comunidade sobre a análise flexível de período do bloco Analytic (link em inglês) para ver um exemplo de uso de date_start e date_end.
Uso de _in_query, _is_selected e _is_filtered
As variáveis _in_query, _is_selected e _is_filtered fornecem um valor verdadeiro ou falso, conforme mostrado neste exemplo. Consequentemente, é importante escolher o tipo adequado de referência de variável líquida.
Se você quiser determinar se algo está incluído em sua consulta e, em seguida, insira determinado texto com base nisso, use um padrão como este:
{% dynamic if view_name.field_name._in_query %}
something to insert if true
{% dynamic else %}
something to insert if false
{% dynamic endif %}
Se você quiser inserir literalmente a palavra "true" ou "false", use um padrão como este:
{{ view_name.field_name._in_query }}
Alguns dialetos SQL não são compatíveis com as palavras literais "true" e "false". Nesse caso, adicione o filtro sql_boolean para ver os valores verdadeiros e falsos necessários:
{{ view_name.field_name._in_query | sql_boolean }}
Os mesmos padrões se aplicam às variáveis _is_selected e _is_filtered.
Uso de variáveis líquidas com o parâmetro label
Use variáveis Liquid no parâmetro label de um campo para alterar dinamicamente a aparência do campo no seletor de campo e nas visualizações. Consulte a seção Tabela nesta página para ver quais variáveis Liquid funcionam com o parâmetro label.
As variáveis líquidas funcionam com parâmetros de rótulo no nível do campo, incluindo
label,view_label,group_labelegroup_item_label, mas não funcionam com parâmetros de rótulo no modelo, exploração, visualização ou linha de referência ou com rótulo como um subparâmetro delink.
As variáveis a seguir podem ser usadas com label para afetar o seletor de campo, os cabeçalhos de coluna na seção de dados de uma exploração e as visualizações:
_model._name_view._name_explore._name_field._name_user_attributes['name_of_attribute']
As outras variáveis Liquid marcadas com LA na tabela acima, como as que retornam um valor com base em um filtro (como _filters) ou que exigem que uma consulta seja executada antes de o valor da variável ser determinado (como in_query), não alteram o nome do campo no seletor de campo. Nesses casos, o nome do campo só é alterado na visualização resultante.
Ao usar a variável líquida parameter com label, label é transmitido ao valor do subparâmetro value.
Uso de variáveis líquidas com o parâmetro description
É possível usar as variáveis Liquid com o parâmetro description para mudar dinamicamente a descrição de um campo. Essa descrição aparece quando os usuários passam o cursor sobre o ícone de informações do campo no seletor de campo, o nome da coluna do campo na seção de dados de "Explorar" ou o nome da coluna em um gráfico de tabelas. Consulte a tabela na seção Definições de variáveis líquidas nesta página para ver quais variáveis líquidas funcionam com o parâmetro description.
As variáveis líquidas funcionam com o parâmetro
descriptionapenas no nível do campo. Eles não funcionam com o parâmetrodescriptionno nível "Explorar".
As variáveis a seguir podem ser usadas com description para afetar o seletor de campo, a seção de dados de um recurso Explorar e o cabeçalho da coluna em um gráfico de tabelas:
_model._name_view._name_explore._name_field._name_user_attributes['name_of_attribute']
As outras variáveis Liquid marcadas com DE na tabela acima, como as variáveis líquidas que retornam um valor com base em um filtro (como _filters) ou que exigem que uma consulta executada antes que o valor da variável possa ser determinada (como in_query) não alteram a descrição no seletor de campo ou na seção de dados de uma exploração. Essas variáveis líquidas só afetam a descrição mostrada quando um usuário passa o cursor sobre o cabeçalho da coluna do campo em um gráfico de tabelas.
Para exemplos de como usar o Liquid no parâmetro description, consulte a página de documentação do parâmetro description.
Considerações
Referenciando campos yesno
Para referenciar o valor de um campo de yesno, ele diferencia maiúsculas de minúsculas. Use Yes ou No. Exemplo:
{% dynamic if value == 'Yes' %}
Como usar operadores lógicos com variáveis Liquid
É possível usar os operadores lógicos and, or e not com variáveis Liquid. Os operadores lógicos em Liquid diferenciam maiúsculas de minúsculas e precisam ser escritos em letras minúsculas. Exemplo:
{% dynamic if value == "Shirt" or value == "Shoes" %}
This is a shirt or shoes.
{% dynamic endif %}
Erro "Variável não encontrada"
Um motivo para encontrar esse erro no Liquid é se você usar {{ }} e {% %} ao mesmo tempo, desta forma:
{% if value > {{ search_latency_top_hr.limit_95._value }} %}
Em vez disso, faça o seguinte:
{% dynamic if value > search_latency_top_hr.limit_95._value %}
Se você usa um filtro de modelo, verifique se está referenciando um nome de tabela que não se mescla à tabela derivada.
As convenções de nomenclatura podem afetar o agrupamento de consultas
Se houver um campo com o nome value, esse campo será incluído na cláusula GROUP BY de uma consulta de exploração sempre que a variável líquida value for referenciada em outro campo na mesma visualização.
Exemplo:
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
}
Isso gerará o seguinte SQL quando apenas o id for selecionado em uma exploração:
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
Para evitar esse comportamento de agrupamento, defina o escopo da variável value com o nome do campo para referenciar explicitamente o campo:
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 %} ;;
}
O uso de _filters['view_name.field_name'] em uma tabela derivada requer sql_quote
Ao definir uma tabela derivada baseada em SQL, se você usar a variável líquida _filters['view_name.field_name'], em que o valor é renderizado em SQL e o filtro retorna um valor de string, é necessário adicionar aspas simples na saída. Para isso, inclua o filtro sql_quote líquido.
Por exemplo, se você estiver usando uma dessas variáveis Liquid no parâmetro sql de um parâmetro derived_table:
{{ _filters['view_name.field_name'] }}
ou
{% assign foo = _filters['view_name.field_name'] %} foo
É possível anexar o filtro líquido | sql_quote à declaração da variável líquida:
{{ _filters['view_name.field_name'] | sql_quote }}
e
{% assign foo = _filters['view_name.field_name'] | sql_quote %} foo
Veja um exemplo de tabela derivada que usa a variável _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
;;
}
O campo city é uma string que será enviada ao SQL. Portanto, o filtro Liquid sql_quote é necessário para garantir que o SQL de saída esteja entre aspas simples. Na análise resultante, quando um usuário especifica um nome de cidade como filtro, o Looker coloca a string do nome da cidade entre aspas. O Looker envia esse SQL ao banco de dados se um usuário filtrar a consulta "Explorar" com o valor de cidade de New York:
WHERE
users.city = 'New York'
Se você estiver usando a variável Liquid
_filters['view_name.field_name']para um campo de string em uma tabela derivada em que o valor é renderizado em SQL, você receberá o seguinte aviso LookML se não anexar| sql_quoteà variável Liquid:
Using "_filters[]" in Derived Table SQL without "sql_quote" is discouraged.
Também é possível usar sql_quote com essa sintaxe para citar vários valores em uma matriz:
{{ _filters['view_name.field_name'] |split(",") | sql_quote |join(",") }}
Veja um exemplo em que a saída do Liquid é usada como entrada para uma instrução IN:
WHERE
users.city IN({{ _filters['users_sql_based_dt.city'] |split(",") | sql_quote |join(",") }})
Com essa sintaxe, a saída líquida terá aspas em torno de cada valor individual ('value1','value2','value3'), em vez de aspas em toda a lista ('value1, value2, value3').
Variáveis líquidas em medidas agregadas afetam o agrupamento
Quando você usa a sintaxe {{ view_name.field_name._value }} ou {{ field_name._value }} no parâmetro link ou html de uma medida para fazer referência a um valor de outro campo, o Looker extrai esse campo na consulta SQL para capturar o valor dele. Por isso, o Liquid pode afetar como as consultas SQL são geradas e quantas colunas a cláusula GROUP BY usa, o que pode causar um comportamento inesperado quando você está trabalhando com medidas agregadas, como as de type: count.
Por exemplo, suponha que você tenha as duas medidas a seguir:
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 }}"
}
}
Ao gerar uma consulta usando a medida count_without_liquid, você tem os seguintes resultados:
Nesse caso, a consulta retorna uma única contagem para cada mês. O SQL gerado para os resultados anteriores é mostrado a seguir:
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
No entanto, ao gerar uma consulta usando a medida count_with_liquid, você recebe os seguintes resultados:
Este exemplo mostra que, em vez de uma contagem para cada mês na consulta, você recebe uma contagem para cada mês e para cada status. Isso ocorre porque, no SQL gerado, o campo status foi adicionado à consulta para que o valor dela possa ser recuperado. E, como ele foi adicionado à consulta, também foi adicionado à cláusula 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
Uma opção para impedir que isso aconteça é usar a função row[] com a variável Liquid, que extrai o valor dos resultados renderizados no navegador e não adiciona o campo referenciado à consulta 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'] }}"
}
Ao usar essa sintaxe, o parâmetro link só funcionará se o campo for selecionado ou incluído na consulta de outra forma.
Resumindo, o uso da sintaxe row[] não fará com que o campo seja adicionado à consulta como {{ field_name._value }} faz. O rótulo dinâmico fará com que o link não tenha um rótulo se o campo não estiver disponível. Isso fará com que ele desapareça do menu de links.