Filtros com modelo e parâmetros líquidos

Este é um tópico avançado voltado para usuários que têm um bom conhecimento pré-existente de SQL e LookML.

Com o Looker, os usuários conseguem manipular as consultas de forma automática criando filtros com base em dimensões e medidas. Embora esse método atenda a muitos casos de uso, ele não pode habilitar todas as necessidades analíticas. Os filtros com modelo e os parâmetros Liquid ampliam de forma significativa os possíveis casos de uso que você pode oferecer.

Da perspectiva do SQL, as dimensões e as medições só podem alterar as cláusulas WHERE ou HAVING mais externas na consulta. No entanto, você pode querer permitir que os usuários manipulem outras partes do SQL. Ajustar parte de uma tabela derivada, ajustar qual tabela de banco de dados será consultada ou criar dimensões e filtros multiuso são apenas alguns dos recursos que você pode ativar com filtros de modelo e parâmetros líquidos.

Aviso :a persistência não é compatível com tabelas derivadas que usam filtros de modelo ou parâmetros líquidos.

Os filtros com modelo e os parâmetros Liquid usam a linguagem de modelos Liquid para inserir a entrada do usuário em consultas SQL. Primeiro, use um parâmetro do LookML para criar um campo para os usuários interagirem. Em seguida, use uma variável líquida para injetar a entrada do usuário em consultas SQL.

Examples

Vamos conferir alguns exemplos para demonstrar o valor dos filtros com modelo e dos parâmetros líquidos.

Como criar uma tabela derivada dinâmica com um filtro com modelo

Considere uma tabela derivada que calcula o gasto em ciclo de vida de um cliente, na região nordeste:

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,                        -- Can be made a dimension
        SUM(sale_price) AS lifetime_spend   -- Can be made a dimension
      FROM
        order
      WHERE
        region = 'northeast'                -- Can NOT be made a dimension
      GROUP BY 1
    ;;
  }
}

Nesta consulta, é possível criar dimensões de customer_id e lifetime_spend. No entanto, suponha que você queira que o usuário possa especificar o region, em vez de codificar para "northeast". Não é possível expor a region como uma dimensão. Portanto, o usuário não pode filtrá-la normalmente.

Uma opção seria usar um filtro com modelo, que ficaria assim:

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition order_region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  filter: order_region {
    type: string
  }
}

Leia mais na seção Uso básico para instruções detalhadas.

Observação :se uma tabela derivada usar um filtro com modelo, não será possível tornar a tabela persistente.

Como fazer uma medida dinâmica com um parâmetro líquido

Considere uma medida filtrada que some o número de calças vendidas:

measure: pants_count {
  filters: [category: "pants"]
}

Isso é simples, mas se houvesse dezenas de categorias, seria tedioso criar uma medida para cada uma. Além disso, a experiência do Explorar pode ficar confusa para os usuários.

Uma alternativa seria criar uma medida dinâmica como esta:

measure: category_count {
  type: sum
  sql:
    CASE
      WHEN ${category} = '{% parameter category_to_count %}'
      THEN 1
      ELSE 0
    END
  ;;
}

parameter: category_to_count {
  type: string
}

Leia mais na seção Uso básico para ver instruções detalhadas.

Uso básico

Etapa 1: criar algo para o usuário interagir

• Para filtros com modelo, adicione um filter.
• Para parâmetros líquidos, adicione um parameter.

Em ambos os casos, esses campos aparecerão para o usuário na seção Campos somente para filtros do seletor de campo.

Os campos filter e parameter podem aceitar uma série de parâmetros filhos, permitindo que você personalize a forma como eles funcionam. Consulte a página de documentação Parâmetros de campo para ver uma lista completa. Há duas opções com menção especial aos campos parameter.

Primeiro, os campos parameter podem ter um tipo especial chamado sem aspas:

parameter: table_name {
  type: unquoted
}

Esse tipo permite que os valores sejam inseridos no SQL sem ficarem entre aspas, como uma string seria. Isso pode ser útil quando você precisa inserir valores SQL, como nomes de tabelas.

Em segundo lugar, os campos parameter têm uma opção chamada valores permitidos que permite associar um nome fácil de usar ao valor que você quer inserir. Exemplo:

  parameter: sale_price_metric_picker {
    description: "Use with the Sale Price Metric measure"
    type: unquoted
    allowed_value: {
      label: "Total Sale Price"
      value: "SUM"
    }
    allowed_value: {
      label: "Average Sale Price"
      value: "AVG"
    }
    allowed_value: {
      label: "Maximum Sale Price"
      value: "MAX"
    }
    allowed_value: {
      label: "Minimum Sale Price"
      value: "MIN"
    }
  }

Etapa 2: aplicar a entrada do usuário

A segunda etapa é usar Liquid para adicionar o filtro modelo ou o parâmetro Líquido, conforme desejado.

Filtros com modelo

A sintaxe dos filtros com modelo é dividida da seguinte forma:

{% condition filter_name %} sql_or_lookml_reference {% endcondition %}

• As palavras condition e endcondition nunca mudam.
• Substitua filter_name pelo nome do filtro criado na primeira etapa. Você também pode usar uma dimensão se não tiver criado um campo somente para filtro.
• Substitua sql_or_lookml_reference pelo SQL ou LookML que precisa ser definido como "igual" à entrada do usuário. Isso será explicado com mais detalhes posteriormente nesta seção. Se estiver usando o LookML, use a sintaxe do LookML ${view_name.field_name}.

No exemplo anterior, Como criar uma tabela derivada dinâmica com um filtro com modelo, usamos:

{% condition order_region %} order.region {% endcondition %}

É importante entender a interação entre as tags Liquid e o SQL que você escreve entre as tags. Essas tags de filtro com modelo são sempre transformadas em uma expressão lógica. Por exemplo, se o usuário inserir "Nordeste" no filtro order_region, o Looker vai transformar essas tags no seguinte:

order.region = 'Northeast'

Em outras palavras, o Looker interpreta a entrada do usuário e gera a expressão lógica apropriada.

Observação :isso geralmente é um ponto de confusão entre os desenvolvedores do Looker. Os filtros com modelo sempre resultam em uma expressão lógica de algum tipo, e não no valor individual inserido por um usuário.

Como os filtros com modelo retornam uma expressão lógica, é possível usá-los com outros operadores e expressões lógicas válidos na instrução WHERE do SQL. Usando o exemplo anterior, se você quisesse retornar todos os valores, exceto a região que o usuário selecionou, use o seguinte na instrução WHERE:

NOT ({% condition order_region %} order.region {% endcondition %})

Também é válido usar um campo do LookML como condição de filtro. Todos os filtros aplicados diretamente ao campo do LookML determinarão o valor da instrução WHERE:

view: customer_facts {
  derived_table: {
    sql:
      SELECT
        customer_id,
        SUM(sale_price) AS lifetime_spend
      FROM
        order
      WHERE
        {% condition region %} order.region {% endcondition %}
      GROUP BY 1
    ;;
  }

  dimension: region {
    type: string
    sql: ${TABLE}.region ;;
}

Parâmetros líquidos

A sintaxe para parâmetros líquidos é dividida da seguinte forma:

{% parameter parameter_name %}

• A palavra parameter nunca muda.
• Substitua parameter_name pelo nome do parameter que você criou na primeira etapa.

Por exemplo, para aplicar a entrada do campo parameter na primeira etapa, crie uma medição como esta:

  measure: sale_price_metric {
    description: "Use with the Sale Price Metric Picker filter-only field"
    type: number
    label_from_parameter: sale_price_metric_picker
    sql: {% parameter sale_price_metric_picker %}(${sale_price}) ;;
    value_format_name: usd
  }

Como escolher entre filtros com modelo e parâmetros líquidos

Embora os filtros de modelo e os parâmetros líquidos sejam semelhantes, há uma diferença importante entre eles:

• Os parâmetros líquidos inserem a entrada do usuário diretamente ou usando os valores definidos com valores permitidos.
• Os filtros com modelo inserem valores como instruções lógicas, conforme descrito na seção Filtros com modelo.

Quando você quiser oferecer aos usuários entradas mais flexíveis (por exemplo, com vários tipos de períodos ou pesquisas de strings), tente usar filtros de modelo sempre que possível. O Looker interpreta a entrada do usuário e escreve o SQL apropriado em segundo plano. Isso evita que você tenha que considerar todos os tipos possíveis de entradas do usuário.

Em situações em que uma instrução lógica não pode ser inserida ou em que você conhece um conjunto finito de opções que o usuário pode inserir, use os parâmetros líquidos.