Filtros com modelos e parâmetros líquidos

Este é um tópico avançado destinado a usuários com um bom conhecimento prévio de SQL e LookML.

O Looker oferece automaticamente aos usuários a capacidade de manipular as consultas criando filtros, que são baseados em dimensões e medidas. Embora esse método atenda a muitos casos de uso, ele não pode atender a todas as necessidades analíticas. Os filtros com modelos e os parâmetros do Liquid ampliam muito os possíveis casos de uso que você pode oferecer suporte.

Do ponto de vista do SQL, as dimensões e as métricas só podem alterar as cláusulas WHERE ou HAVING mais externas na sua consulta. No entanto, talvez você queira permitir que os usuários manipulem outras partes do SQL. Ajustar parte de uma tabela derivada, ajustar qual tabela de banco de dados é consultada ou criar dimensões e filtros multifuncionais são apenas alguns dos recursos que você pode ativar com filtros baseados em modelos e parâmetros Liquid.

Os filtros com modelo e os parâmetros do Liquid usam a linguagem de modelo do Liquid para inserir a entrada do usuário em consultas SQL. Primeiro, você usa um parâmetro da LookML para criar um campo em que os usuários podem interagir. Em seguida, use uma variável Liquid para injetar a entrada do usuário em consultas SQL.

Exemplos

Vamos analisar alguns exemplos para demonstrar o valor dos filtros com modelo e dos parâmetros Liquid.

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

Considere uma tabela derivada que calcula o gasto vitalício 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
    ;;
  }
}

Nessa consulta, é possível criar dimensões com base em customer_id e lifetime_spend. No entanto, suponha que você queira que o usuário possa especificar o region em vez de codificá-lo como "northeast". O region não pode ser exposto como uma dimensão. Portanto, o usuário não pode filtrar normalmente.

Uma opção seria usar um filtro com modelo, que teria esta aparência:

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.

Como criar uma métrica dinâmica com um parâmetro do Liquid

Considere uma métrica filtrada que soma o número de calças vendidas:

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

Isso é simples, mas se houvesse dezenas de categorias, seria cansativo criar uma métrica para cada uma. Além disso, ela pode prejudicar a experiência de navegação dos usuários.

Uma alternativa seria criar uma métrica dinâmica assim:

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 instruções detalhadas.

Uso básico

Etapa 1: crie algo para o usuário interagir

  • Para filtros com modelo, adicione um filter.
  • Para parâmetros do Liquid, adicione um parameter.

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

Os campos filter e parameter podem aceitar uma série de parâmetros filhos, permitindo personalizar a operação deles. Consulte a página de documentação Parâmetros de campo para ver uma lista completa. Há duas opções que merecem menção especial para 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 serem colocados entre aspas, como uma string. 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 o Liquid para adicionar o filtro com modelo ou o parâmetro do Liquid conforme desejado.

Filtros com modelo

A sintaxe dos filtros com modelo é assim:

{% condition filter_name %} sql_or_lookml_reference {% endcondition %}
  • As palavras condition e endcondition nunca mudam.
  • Substitua filter_name pelo nome do filtro que você criou 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 deve ser definido como "igual" à entrada do usuário. Isso será explicado com mais detalhes mais adiante nesta seção. Se você estiver usando o LookML, use a sintaxe ${view_name.field_name} do LookML.

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 elas. 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 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 adequada.

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 SQL WHERE. Usando o exemplo anterior, se você quisesse retornar todos os valores exceto a região selecionada pelo usuário, poderia usar o seguinte na instrução WHERE:

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

Também é válido usar um campo da LookML como condição de filtro. Todos os filtros aplicados diretamente ao campo da 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 de líquidos

A sintaxe dos parâmetros do Liquid é assim:

{% 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 etapa 1, crie uma métrica assim:

  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 do Liquid

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

  • Os parâmetros do Liquid 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".

Em situações em que você quer oferecer aos usuários uma entrada mais flexível (como vários tipos de períodos ou pesquisas de string), tente usar filtros com modelos sempre que possível. O Looker pode interpretar a entrada do usuário e escrever o SQL apropriado nos bastidores. Assim, você não precisa considerar todos os tipos possíveis de entrada do usuário.

Em situações em que não é possível inserir uma instrução lógica ou quando você conhece um conjunto finito de opções que o usuário pode inserir, use parâmetros do Liquid.