parâmetro

Uso

visualização: view_name {
parameter: parameter_name { ... }
}
Hierarquia
view
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 a z (sem letras maiúsculas), 0 a 9 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 com parameter 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 Variable.

  • 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 com a estrutura lógica {% dynamic if %}, {% elsif %} e {% dynamic endif %} para determinar o valor da dimensão, com base no valor de 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 exige que você coloque os valores do 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 produz uma instrução SQL avaliada como 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' %} nem o {% dynamic if yesno_parameter._parameter_value %} funcionam corretamente.

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