Uso
parameter: parameter_name { ... }
}
Hierarquia
parameter |
Aceita
Um identificador do Looker para nomear o parâmetro |
Definição
Na verdade, há um parâmetro LookML chamado "parameter
". O parâmetro parameter
cria um campo somente filtro que pode ser usado para filtrar "explores", "looks" e painéis, mas que não pode ser adicionado a um conjunto de resultados. O valor que um usuário seleciona para esse campo de filtro pode criar resultados de consulta interativos, rótulos, URLs e muito mais quando usado com as variáveis Liquid {% parameter parameter_name %}
e parameter_name._parameter_value
. O parâmetro parameter
também pode simplificar os modelos LookML, já que diferentes resultados podem ser exibidos em um único campo.
Com os campos de filtro de parâmetro, os usuários podem selecionar apenas um valor de filtro para um campo, e a condição é definida como
is equal to
. Se você quiser que os usuários insiram vários valores de filtro de uma só vez e aproveitem a lógica do filtro SQL gerado com mais simplificação do Looker (contains
,does not contain
etc.), consulte a página de documentação de Filtros com modelo para mais detalhes.
Um nome parameter
precisa:
- Ser único em uma visualização
- Consiste em caracteres
a
az
(sem letras maiúsculas),0
a9
ou_
. - Começar com uma letra
Também há muitos parâmetros de campo que podem ser usados com parameter
, incluindo default_value
e allowed_value
. Consulte a subseção a seguir, Especificar valores permitidos, para ver exemplos que usam o parâmetro de campo allowed_value
.
Evite usar
default_value
comparameter
se os dados tiverem valores com sublinhados.
Especificar valores permitidos
Por padrão, um usuário pode inserir qualquer valor único em um filtro criado por um parâmetro parameter
. Se você quiser limitar os valores específicos que um usuário pode escolher, use allowed_value
. Os valores permitidos especificam pares de valores e valores que um usuário pode escolher.
O parâmetro allowed_value
é semelhante ao suggestions
, que permite definir as opções de filtro que o usuário pode escolher. No entanto, o parâmetro allowed_value
adiciona a funcionalidade extra de mapear um rótulo fácil de usar com o valor que você quer injetar na consulta SQL subjacente.
Por exemplo, isso produziria um parameter
que oferece ao usuário três opções de filtro:
parameter: number_of_results {
type: string
allowed_value: {
label: "Less than 500"
value: "< 500"
}
allowed_value: {
label: "Less than 10,000"
value: "< 10000"
}
allowed_value: {
label: "All Results"
value: "> 0"
}
}
O label
é o que o usuário verá nas sugestões de filtro, e value
contém o valor que será inserido nas consultas SQL com variáveis líquidas para criar conteúdo interativo.
O filtro resultante ficará assim:
Como usar o parameter
com líquido
Há dois tipos de uso de líquidos, conforme mencionado na página de referência de variáveis.
Quando parameter
é usado com Liquid, é mais comum usar a sintaxe de tag {% %}
, que é usada para criar instruções condicionais lógicas.
Duas variáveis Liquid que podem ser usadas com parameter
são: {% parameter parameter_name %}
e parameter_name._parameter_value
. Vamos apresentar exemplos de cada uma nas próximas seções.
Inserir valores selecionados pelo usuário com {% verbatim %}{% parameter parameter_name %}
A variável Liquid {% parameter parameter_name %}
usa a tag Liquid {% parameter %}
em conjunto com o nome do parâmetro para inserir um valor selecionado pelo usuário diretamente em uma consulta SQL subjacente.
- A palavra parâmetro nunca muda.
- Substitua parameter_name pelo nome do parâmetro criado.
Se um parâmetro for definido em um arquivo de visualização diferente daquele em que é referenciado, defina o escopo do nome do parâmetro com o nome da visualização, por exemplo, view_name.parameter_name
.
Exemplo
Neste exemplo, criamos um parameter
chamado item_to_add_up
que permite ao usuário escolher qual coluna do banco de dados ele quer somar: sale_price
, cost
ou profit
:
parameter: item_to_add_up {
type: unquoted
allowed_value: {
label: "Total Sale Price"
value: "sale_price"
}
allowed_value: {
label: "Total Cost"
value: "cost"
}
allowed_value: {
label: "Total Profit"
value: "profit"
}
}
Em seguida, vamos criar uma medida chamada dynamic_sum
.
Essa medida faz referência à variável Liquid {% parameter parameter_name %}
no parâmetro sql
, que injeta o valor selecionado de item_to_add_up
e muda o nome da coluna que está sendo referenciada. A medida realiza o cálculo na coluna referenciada:
measure: dynamic_sum {
type: sum
sql: ${TABLE}.{% parameter item_to_add_up %} ;;
value_format_name: "usd"
}
O resultado é uma exploração interativa que exibe diferentes agregações representadas por uma medida, mostrada abaixo:
Consulte o artigo Ótimos casos de uso para campos de parâmetro na Central de Ajuda para ver mais exemplos de como usar parameter
com a variável {% parameter parameter_name %}
.
Como criar instruções lógicas com parameter_name._parameter_value
Também é possível injetar o valor de um parameter
em uma consulta SQL usando uma instrução lógica Liquid {% %}
com a parameter_name._parameter_value
- Substitua parameter_name pelo nome do parâmetro criado.
- O ._parameter_value não vai mudar.
Se um parâmetro for definido em um arquivo de visualização diferente daquele em que é referenciado, defina o escopo do nome do parâmetro com o nome da visualização, por exemplo, view_name.parameter_name._parameter_value
.
parameter_name._parameter_value
permite instruções lógicas complexas usando valores possíveis de um parâmetro. Isso é semelhante a uma instrução CASE WHEN
em SQL.
Uma instrução condicional Liquid usa a seguinte sintaxe:
{% dynamic if %}
para criar uma condição{% elsif %}
para criar condições adicionais após a condição inicial{% dynamic else %}
para definir um valor a ser retornado quando as outras condições não forem atendidas{% dynamic endif %}
para finalizar a instrução
Essa lógica de Liquid pode ser usada com variáveis Liquid e LookML de várias maneiras. Consulte a página de documentação Referência de variáveis líquidas para ver uma lista completa dos possíveis locais em que a variável parameter_name._parameter_value
é usada com o líquido no LookML. Veja a seguir exemplos que usam os parâmetros sql
e html
.
Exemplo de SQL
O bloco LookML a seguir cria um parameter
chamado date_granularity
. Em seguida, o parâmetro sql
de uma dimensão usa parameter_name._parameter_value
{% dynamic if %}
{% elsif %}
{% dynamic endif %}
parameter
:
parameter: date_granularity {
type: unquoted
allowed_value: {
label: "Break down by Day"
value: "day"
}
allowed_value: {
label: "Break down by Month"
value: "month"
}
}
dimension: date {
sql:
{% dynamic if date_granularity._parameter_value == 'day' %}
${created_date}
{% elsif date_granularity._parameter_value == 'month' %}
${created_month}
{% dynamic else %}
${created_date}
{% dynamic endif %};;
}
O resultado final é um campo de data interativo que os usuários podem mudar para exibir os resultados em diferentes períodos:
Exemplo de HTML
O parameter_name._parameter_value
também pode ser usado com um parâmetro html
para criar formatação interativa de resultados.
Usando o exemplo acima, podemos mudar a cor do texto dependendo da granularidade da data que um usuário selecionar adicionando um parâmetro html
com uma instrução lógica {% dynamic if %}
semelhante:
parameter: date_granularity {
type: unquoted
allowed_value: {
label: "Break down by Day"
value: "day"
}
allowed_value: {
label: "Break down by Month"
value: "month"
}
}
dimension: date {
sql:
{% dynamic if date_granularity._parameter_value == 'day' %}
${created_date}
{% elsif date_granularity._parameter_value == 'month' %}
${created_month}
{% dynamic else %}
${created_date}
{% dynamic endif %};;
html:
{% dynamic if date_granularity._parameter_value == 'day' %}
<font color="darkgreen">{{ rendered_value }}</font>
{% elsif date_granularity._parameter_value == 'month' %}
<font color="darkred">{{ rendered_value }}</font>
{% dynamic else %}
<font color="black">{{ rendered_value }}</font>
{% dynamic endif %};;
}
A variável Liquid rendered_value
é usada na instrução html
com tags de objeto Liquid, {{ }}
, para gerar o valor do campo com a formatação padrão do Looker nos resultados.
O resultado final é uma formatação condicional interativa que depende do valor selecionado pelo usuário:
Consulte a página de documentação html
e o artigo da Central de Ajuda Como mudar cores e fontes usando HTML para ver mais exemplos de interatividade líquida para HTML.
Tipos de parameter
Vários tipos de campo podem ser atribuídos a um parâmetro parameter
. Alguns casos especiais são detalhados nesta página.
parameters
de type: string
Quando você usa um parameter
com type: string
, a variável Liquid parameter_name._parameter_value
parameter
entre aspas simples e duplas. Dessa forma, as aspas simples são transmitidas ao SQL, identificando o valor como um valor de string. Veja o exemplo a seguir:
parameter: date_granularity {
type: string
allowed_value: { value: "Day" }
allowed_value: { value: "Month" }
}
dimension: date {
label_from_parameter: date_granularity
sql:
{% dynamic if date_granularity._parameter_value == "'Day'" %}
${created_date}::VARCHAR
{% elsif date_granularity._parameter_value == "'Month'" %}
${created_month}::VARCHAR
{% dynamic else %}
NULL
{% dynamic endif %} ;;
}
Além disso, se você quiser incluir o valor de um parameter
com type: string
em um label
, coloque aspas "`" antes das aspas duplas:
label: "{% dynamic if test._parameter_value == \\\\"'foo'\\\\" %} 'SUCCESS' {% dynamic else %} 'FAIL' {% dynamic endif %}"
parameters
de type: yesno
Quando você usa um parameter
com type: yesno
, a variável Liquid parameter_name._parameter_value
true
, conforme apropriado para seu dialeto SQL. Portanto, sugerimos que você não use parameters
de type: yesno
em instruções lógicas de líquido. Nem o {% dynamic if yesno_parameter._parameter_value == 'Yes' %}
{% dynamic if yesno_parameter._parameter_value %}
parameters
de type: unquoted
O tipo unquoted
é semelhante ao type: string
, mas quando o valor de parameter
é inserido na variável líquida ({% parameter %}
) não é citado. Isso é útil quando você está inserindo valores no SQL, como nomes de colunas ou tabelas, que não podem ser citados para funcionar corretamente (como nos exemplos acima).
Inserir valores sem aspas diretamente no SQL pode criar a possibilidade de ações SQL indesejadas. Para resolver isso, os valores parameter
de type: unquoted
são restritos aos caracteres de A a Z e 0 a 9 (sem espaços ou outros caracteres especiais).
Por exemplo, o LookML a seguir cria um parameter
chamado table_name
, que produzirá um valor sem aspas:
parameter: table_name {
type: unquoted
}
parameters
de type: date_time
Um tipo date_time
parameter
permite que os usuários selecionem uma data específica em um filtro. A granularidade mais profunda disponível é YYYY/MM/DD
. Os usuários podem selecionar apenas um valor de filtro de data, e a condição de filtro pode ser definida como is on the day
para selecionar uma data ou matches a user attribute
para selecionar um atributo de usuário de data/hora.
Por exemplo, aqui está um parâmetro date_time
, chamado date_selector
:
parameter: date_selector {
type: date_time
description: "Use this field to select a date to filter results by."
}
Quando selecionado em "Explorar", o seletor de data permite que os usuários selecionem uma data específica:
Se você quiser que os usuários aproveitem a lógica de filtro de data do SQL gerada pelo Looker (is in the past
, is in range
etc.), consulte a página de documentação de Filtros com modelo para mais detalhes.
Recursos adicionais
A página de documentação de Filtros com modelo mostra mais exemplos de expressões lógicas e casos de uso para
parameter
.A Central de Ajuda é um ótimo recurso para exemplos de caso de uso de líquidos. O artigo furação personalizada usando HTML e link da Central de Ajuda mostra como usar o líquido com os parâmetros
link
ehtml
para criar detalhamentos personalizados. O artigo Análises de dados mais eficientes da Central de Ajuda mostra soluções de perfuração personalizadas mais avançadas que usamhtml
elink
.