Técnicas avançadas para visualizações de métricas

Técnicas avançadas para exibições de métrica permitem expressar lógica de negócios complexa e reutilizar definições em sua camada semântica. Esta página explica duas dessas técnicas:

• Medidas de janela: para cálculos em séries temporais, como médias móveis, totais acumulados e variações entre períodos.
• Componibilidade: para criar medidas complexas referenciando outras medidas em vez de reescrever sua lógica.

Esta página pressupõe familiaridade com os conceitos básicos de modelagem de exibição de métrica. Consulte visões de métricas do modelo.

Dimensões da janela

As medidas de janelas permitem definir medidas com agregações por janela, cumulativas ou semi-aditivas nas suas visualizações de métricas. Eles oferecem suporte a cálculos como médias móveis, variações entre períodos e totais acumulados.

Você pode adicionar uma medida de janela no editor do Catalog Explorer ou no YAML.

Adicionar uma medida de janela no editor

Na guia interface do usuário do editor de exibição de métrica, clique em + Janela ao editar uma medida. + A janela está disponível no modo Construtor e Personalizado . As opções de janela no editor correspondem aos campos YAML descritos em Definir uma medida de janela.

Para obter mais informações sobre como criar e editar medidas, consulte Criar uma exibição de métrica.

Definir uma medida de janela

Uma medida de janela inclui os seguintes campos necessários:

• order: O campo que determina a ordenação da janela.

• intervalo: define a extensão da janela. Os valores compatíveis incluem: current, cumulative, trailing, leading e all. Para ver a sintaxe completa e as descrições, consulte Valores com range suporte. Para mais detalhes sobre os modificadores inclusive e exclusive em trailing e leading, consulte Incluir ou excluir a linha de âncora.

• semiaditiva: especifica como agregar a medida quando o campo de ordem não está incluído na consulta GROUP BY. Valores possíveis: first e last.

Uma medida de janela também dá suporte ao seguinte campo opcional:

• deslocamento: desloca o quadro de janela para trás ou para frente ao longo do campo order por um intervalo fixo. Use isto para medidas de comparação entre períodos, como de um mês para o outro ou de um ano para o outro. Para sintaxe, unidades com suporte e restrições, consulte as medidas de janela.

Você também pode referenciar um parâmetro inteiro como o valor de range ou offset de uma medida de janela, para que o chamador passe o tamanho da janela no momento da consulta. Veja Passar um tamanho de janela como parâmetro.

Como offset desloca o quadro da janela

Consulte a disponibilidade do recurso de exibição de métrica para requisitos mínimos de computação e versão de especificação YAML.

O campo range define a forma da janela em relação à linha de âncora, e offset desloca esse quadro pelo intervalo especificado ao longo de order. A seguinte tabela mostra o quadro para cada valor de range, com e sem offset de k, em relação à linha de âncora t:

offset é independente de semiadditive. A opção first ou last ainda controla como a medida é reduzida quando order não está no GROUP BY da consulta.

Para obter melhores resultados, combine offset com o grão natural de order. Para dados mensais, offset: -12 month é preferível a offset: -365 day porque a aritmética de mês e ano leva em conta meses com durações variáveis e anos bissextos, enquanto a aritmética de day não o faz.

Incluir ou excluir a linha de âncora

Consulte a disponibilidade do recurso de exibição de métrica para requisitos mínimos de computação e versão de especificação YAML.

Para os intervalos trailing e leading, a palavra-chave opcional inclusive ou exclusive controla se o valor da janela da linha âncora (por exemplo, hoje) faz parte da janela sem interrupção:

O exemplo a seguir mostra como inclusive e exclusive afetam a janela sem interrupção para a data âncora 2025-01-05 com trailing 3 day.

Suponha que os dados subjacentes têm uma linha por dia com os seguintes valores:

Cada modificador seleciona três dias de linhas em relação à âncora e soma seus valores:

Os intervalos leading seguem a mesma lógica na direção oposta.

Exemplo de medida com janela retrospectiva, móvel ou prospectiva

O exemplo a seguir calcula uma contagem contínua de 7 dias dos clientes que fizeram pedidos. Essa métrica acompanha as tendências de engajamento do cliente ao longo do tempo, mostrando quantos clientes distintos fizeram compras na semana que antecede cada data.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate

measures:
  - name: t7d_customers
    expr: COUNT(DISTINCT o_custkey)
    window:
      - order: date
        range: trailing 7 day
        semiadditive: last

Para este exemplo, a seguinte configuração se aplica:

• order: date especifica que o date campo ordena a janela.
• range: trailing 7 day define a janela como os 7 dias anteriores a cada data, excluindo a própria data.
• semiadditive: last retorna o último valor na janela de 7 dias quando date não é uma coluna de agrupamento.

CREATE OR REPLACE VIEW catalog.schema.rolling_customers WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1

  source: samples.tpch.orders
  filter: o_orderdate > DATE'1998-01-01'

  fields:
    - name: date
      expr: o_orderdate

  measures:
    - name: t7d_customers
      expr: COUNT(DISTINCT o_custkey)
      window:
        - order: date
          range: trailing 7 day
          semiadditive: last
$$

Exemplo de medida de janela de comparação entre períodos

O exemplo a seguir calcula o crescimento das vendas diários comparando a receita atual (soma de todos os preços dos pedidos) com a receita de ontem. Essa métrica identifica tendências diárias de vendas e mostra a variação percentual na receita.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
measures:
  - name: previous_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: trailing 1 day
        semiadditive: last
  - name: current_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: current
        semiadditive: last
  - name: day_over_day_growth
    expr: (MEASURE(current_day_sales) - MEASURE(previous_day_sales)) / MEASURE(previous_day_sales) * 100

Para este exemplo, a seguinte configuração se aplica:

• O exemplo usa duas medidas de janela: uma para calcular o total de vendas do dia anterior e outra para calcular o total de vendas do dia atual.
• Uma terceira medida calcula a alteração percentual (crescimento) entre os dias atuais e anteriores.

Exemplo de medida da janela ano a ano usando offset

O modificador offset é o elemento básico para métricas entre períodos. Defina uma cópia deslocada de uma medida base e, em seguida, combine as duas para expressar deltas, razões ou taxas de crescimento diretamente na exibição de métricas.

O exemplo a seguir calcula o crescimento das vendas ano a ano comparando as vendas de cada mês com o mesmo mês do ano anterior. A medida deslocada usa offset: -12 month para retroceder 12 meses ao longo do campo month.

version: 1.1
source: main.default.monthly_sales

fields:
  - name: month
    expr: month
  - name: category
    expr: category

measures:
  - name: monthly_sales
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last

  - name: monthly_sales_py
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last
        offset: -12 month

  - name: yoy_growth
    expr: MEASURE(monthly_sales) - MEASURE(monthly_sales_py)

  - name: yoy_growth_pct
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0)

Para este exemplo, a seguinte configuração se aplica:

• monthly_sales é a medida base, somando as vendas do mês atual.
• monthly_sales_py é a mesma medida deslocada para trás por 12 meses usando offset: -12 month. Para janeiro de 2025, ele retorna o valor de janeiro de 2024.
• yoy_growth e yoy_growth_pct compõem as duas medidas para expressar a variação absoluta e percentual. O uso NULLIF evita erros de divisão por zero quando o valor do ano anterior é zero.

Exemplo de medida total cumulativa (em execução)

O exemplo a seguir calcula a receita cumulativa de vendas desde o início do conjunto de dados até cada data. Esse total em execução mostra a quantidade de receita total gerada ao longo do tempo, útil para acompanhar o progresso em direção às metas de receita anuais ou analisar padrões de crescimento de longo prazo.

version: 1.1
source: samples.tpch.orders

filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: customer
    expr: o_custkey

measures:
  - name: running_total_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last

Para este exemplo, a seguinte configuração se aplica:

• order: date organiza a janela em ordem cronológica.
• range: cumulative define a janela como todos os dados desde o início do conjunto de dados até e incluindo cada data.
• semiadditive: last exibe o valor cumulativo mais recente quando date não está incluído em GROUP BY da consulta, em vez de somar todos os valores das datas.

Exemplo de medida de período a data

O exemplo a seguir calcula a receita de vendas do ano até a data (YTD). Essa medida mostra a receita cumulativa gerada a partir de 1º de janeiro de cada ano até a data atual, redefinindo no início de cada ano novo.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1997-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)
measures:
  - name: ytd_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last
      - order: year
        range: current
        semiadditive: last

Para este exemplo, a seguinte configuração se aplica:

• O exemplo usa duas especificações de janela: uma para a soma cumulativa sobre o date campo e outra para limitar a soma ao current ano.
• O campo year restringe a soma cumulativa para que seja reiniciada no início de cada novo ano.
• Os campos month e year formam uma hierarquia de data no campo de ordem date: cada um é definido pelo nome no campo date, não na coluna subjacente o_orderdate, para que as consultas possam agrupar essa medida por esses campos. Consulte Agrupar por um campo de hierarquia de data.

Exemplo de medida semiadditiva

O exemplo a seguir calcula os saldos da conta, que não devem ser resumidos entre datas (você não pode adicionar o saldo de segunda-feira ao saldo de terça-feira para obter o saldo total). Em vez disso, ao agregar em vários dias, a medida retorna o saldo mais recente. No entanto, a medida ainda pode ser somada entre todos os clientes para mostrar o saldo total em todas as contas em um determinado dia.

version: 1.1

fields:
  - name: date
    expr: date
  - name: customer
    expr: customer_id

measures:
  - name: semiadditive_balance
    expr: SUM(balance)
    window:
      - order: date
        range: current
        semiadditive: last

Para este exemplo, a seguinte configuração se aplica:

• order: date organiza a janela em ordem cronológica.
• range: current restringe a janela a um único dia sem agregação ao longo dos dias.
• semiadditive: last retorna o saldo mais recente ao agregar dados de vários dias.

Consultar uma medida de janela

Você pode consultar uma exibição de métrica com uma medida de janela como qualquer outra exibição de métrica. Uma medida de janela é calculada com base no campo order, portanto, uma consulta que divide os resultados ao longo do tempo deve fazer referência a esse campo, diretamente ou por meio de um campo de hierarquia de datas definido com base nele. Quando a consulta não faz referência ao campo de ordem, a semiadditive palavra-chave determina o valor retornado, conforme descrito no exemplo de medida semiadditiva.

O seguinte exemplo agrupa uma medida de janela por state e por uma expressão de mês sobre o campo de ordem date:

SELECT
   state,
   DATE_TRUNC('month', date),
   MEASURE(t7d_customers) as m
FROM my_metric_view
WHERE date >= DATE'2024-06-01'
GROUP BY ALL

Agrupar por um campo de hierarquia de datas

Uma hierarquia de datas agrega o campo de ordem em granularidades mais amplas, como semana, mês ou ano. Defina cada nível como um campo sobre o campo de ordem pelo nome, não pela coluna de origem subjacente:

fields:
  - name: date
    expr: o_orderdate
  # Date hierarchy: each level is defined on the order field `date`,
  # not on the underlying o_orderdate column.
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)

Agrupar uma medida de janela por um nível de hierarquia exibe a medida nesse nível de granularidade. Supondo que o exemplo de período até a data seja criado como ytd_metric_view, como no exemplo de medida de período até a data, a consulta a seguir retorna o valor de YTD na última data de cada mês:

SELECT month, MEASURE(ytd_sales) AS ytd_sales
FROM ytd_metric_view
GROUP BY month
ORDER BY month;

Modularidade

As exibições de métricas são combináveis. Você pode criar novos campos e medidas que referenciam os existentes em vez de reescrever a lógica do zero. Isso reduz a duplicação e torna as definições de métrica complexas mais fáceis de manter.

A capacidade de composição funciona em dois níveis: em uma única exibição de métrica e entre exibições de métrica quando uma exibição de métrica é usada como fonte de outra.

A composição dá suporte aos seguintes padrões de referência:

• Campos anteriores em novos campos.
• Campos e medidas anteriores nas novas medidas.
• Campos de visualizações de métricas usados como fonte para novos campos.
• Campos e medidas de visualizações métricas usados como fonte para novas medidas.

Definir medidas com composabilidade

Na seção measures, você pode fazer referência a medidas da origem das métricas ou medidas definidas anteriormente na mesma exibição de métrica. Essa abordagem melhora a consistência, a auditabilidade e a manutenção da camada semântica.

Exemplo: Valor médio do pedido (AOV)

O exemplo a seguir define o Valor médio da ordem (AOV) usando duas medidas atômicas: total_revenue (soma dos preços dos pedidos) e order_count (número de pedidos). A avg_order_value medida faz referência a ambas as medidas atômicas.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Revenue
  - name: total_revenue
    expr: SUM(o_totalprice)

  # Order Count
  - name: order_count
    expr: COUNT(1)

  # Composed Measure: Average Order Value (AOV)
  - name: avg_order_value
    # Defines AOV as Total Revenue divided by Order Count
    expr: MEASURE(total_revenue) / MEASURE(order_count)

Se a total_revenue definição for alterada (por exemplo, para excluir impostos), avg_order_value usará automaticamente a definição atualizada.

Composibilidade com lógica condicional

Você pode usar a capacidade de composição para criar proporções complexas, percentuais condicionais e taxas de crescimento sem depender de funções de janela para cálculos simples de período a período.

Exemplo: taxa de cumprimento

O exemplo a seguir calcula a taxa de atendimento: o percentual de pedidos com status 'F' (atendido). A medida divide as ordens atendidas pelo total de pedidos.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Orders (denominator)
  - name: total_orders
    expr: COUNT(1)

  # Fulfilled Orders (numerator)
  - name: fulfilled_orders
    expr: COUNT(1) FILTER (WHERE o_orderstatus = 'F')

  # Composed Measure: Fulfillment Rate (Ratio)
  - name: fulfillment_rate
    expr: MEASURE(fulfilled_orders) / MEASURE(total_orders)
    format:
      type: percentage

Práticas recomendadas para composabilidade

1. Defina as medidas atômicas primeiro: estabeleça medidas fundamentais (SUM, COUNT, AVG) antes de definir medidas que as referenciam.
2. Use MEASURE() para referências: use a função MEASURE() ao fazer referência a outra medida em um expr. Não repita a lógica de agregação manualmente. Por exemplo, evite SUM(a) / COUNT(b) se medidas para ambos os valores já existirem.
3. Priorizar a legibilidade: redigir medidas usando fórmulas matemáticas claras. Por exemplo, MEASURE(gross_profit) / MEASURE(total_revenue) é mais claro do que uma única expressão SQL complexa.
4. Adicionar metadados semânticos: use metadados semânticos para formatar medidas compostas (por exemplo, porcentagens ou valores monetários) para ferramentas sucessoras. Consulte metadados do agente nas exibições de métricas.

Recursos adicionais

• Exibições de métrica do modelo
• Metadados do agente em visualizações de métricas
• Materialização para visões de métricas
• Referência de sintaxe da visão de métricas em YAML