Filtros padronizados e parâmetros líquidos

Este é um tópico avançado que pressupõe um bom conhecimento pré-existente de SQL e LookML.

O Looker oferece automaticamente aos usuários a capacidade de manipular as consultas com a criação de filtros, que são baseados em dimensões e medidas. Embora esse método simples atenda a muitos casos de uso, ele não atende a todas as necessidades de análise. Os filtros de modelo e os parâmetros líquidas ampliam bastante os possíveis casos de uso compatíveis.

Do ponto de vista do SQL, as dimensões e medidas só podem alterar as cláusulas WHERE ou HAVING mais externas na consulta. No entanto, é possível que você queira permitir que os usuários manipulem outras partes do SQL. O ajuste de parte de uma tabela derivada, o ajuste de qual tabela de banco de dados é consultada ou a criação de dimensões e filtros de várias finalidades são apenas alguns dos recursos que você pode ativar com filtros baseados em modelos e parâmetros de líquido.

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

Examples

Vamos ver alguns exemplos para demonstrar o valor dos filtros de modelo e dos parâmetros de líquido.

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

Considere uma tabela derivada que calcula o gasto total do 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, você pode criar dimensões a partir de customer_id e lifetime_spend. No entanto, suponha que você queira que o usuário possa especificar a region, em vez de codificá-la para "northeast". A region não pode ser exposta como uma dimensão e, portanto, o usuário não pode filtrá-la normalmente.

Uma opção seria usar um filtro de modelo, que seria semelhante a este:

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 abaixo para ver instruções passo a passo.

Se uma tabela derivada usar um filtro de 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 soma o número de calças vendidas:

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

Isso é simples, mas se houver dezenas de categorias, seria tedioso criar uma medida para cada uma. Além disso, isso pode atrapalhar a experiência dos 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 abaixo para ver instruções passo a passo.

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.

Nesses dois casos, os campos serão exibidos ao usuário na seção Campos somente filtro do seletor de campo:

Os campos filter e parameter podem aceitar uma série de parâmetros filhos, permitindo que você personalize o funcionamento deles. 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 estar entre aspas, como seria uma string. Isso pode ser útil quando você precisa inserir valores SQL, como nomes de tabela.

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 de modelo ou o parâmetro Liquid conforme desejado.

Filtros com base em modelo

A sintaxe dos filtros de 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 de filtro.
• Substitua sql_or_lookml_reference pelo SQL ou LookML que precisa ser definido como quot;equal" para a entrada do usuário (leia mais detalhes abaixo). Se estiver usando o LookML, use a sintaxe ${view_name.field_name} do LookML.

No exemplo acima, usamos:

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

É importante entender a interação entre as tags líquidas e o SQL que você escreve entre elas. As tags de filtro com modelo são sempre transformadas em uma expressão lógica. Por exemplo, se o usuário inserisse "quot;Northeast"" no filtro order_region, o Looker transformaria essas tags em: order.region = 'Northeast'. Em outras palavras, o Looker entende a entrada do usuário e gera a expressão lógica adequada.

Isso costuma ser um ponto de confusão entre os desenvolvedores do Looker. Os filtros de 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 padronizados retornam uma expressão lógica, você pode usá-los com outros operadores lógicos e expressões lógicas válidas na instrução WHERE SQL. Usando o exemplo acima, se você quiser retornar todos os valores exceto a região selecionada pelo usuário, use o seguinte na instrução WHERE:

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

Também é válido usar um campo LookML como a condição de filtro. Todos os filtros aplicados diretamente ao campo LookML determinam 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 parameter que você criou na primeira etapa.

Por exemplo, para aplicar a entrada do campo da parameter na etapa 1 acima, crie uma medida 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 de modelo e parâmetros de líquido

Embora os filtros padronizados e os parâmetros Liquid sejam semelhantes, há uma diferença importante entre eles:

• Parâmetros líquidos inserem a entrada do usuário diretamente (ou usando os valores definidos com valores permitidos).
• Os filtros de modelo inserem valores como instruções lógicas, conforme descrito acima.

Em situações em que você quer oferecer aos usuários uma entrada mais flexível (como com vários tipos de períodos ou pesquisas de string), tente usar filtros com modelo quando possível. O Looker pode interpretar a entrada do usuário e escrever o SQL apropriado em segundo plano. Isso evita que você precise considerar todos os tipos possíveis de entrada do usuário.

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