Técnicas avançadas para vistas métricas

Técnicas avançadas para vistas métricas permitem-lhe expressar lógica de negócio complexa e reutilizar definições ao longo da sua camada semântica. Esta página explica duas dessas técnicas:

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

Esta página assume familiaridade com conceitos básicos de modelação em vista métrica. Ver vistas métricas do modelo.

Medidas de janela

As medidas de janela permitem definir medidas com agregações em janela, cumulativas ou semiaditivas em suas exibições métricas. Suportam cálculos como médias móveis, alterações período a período e totais acumulados.

Podes adicionar uma medida de janela no editor do Explorador de Catálogos ou no YAML.

Adicionar uma medida de janela no editor

No separador UI do editor de visualização métrica, clique em + Janela enquanto edita uma medida. A janela + está disponível tanto em modo Construtor como em modo Personalizado . As opções de janela no editor correspondem aos campos YAML descritos em Definir uma medida de janela.

Para mais informações sobre a criação e edição de medidas, consulte Criar uma vista métrica.

Definir uma medida de janela

Uma medida de janela inclui os seguintes campos obrigatórios:

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

• intervalo: Define a extensão da janela. Os valores suportados incluem current, cumulative, trailing, leadinge all. Para sintaxe completa e descrições, veja Valores suportadosrange. Para obter detalhes sobre os modificadores inclusive e exclusive em trailing e leading, consulte Incluir ou excluir a linha âncora.

• semiaditivo: Especifica como agregar a medida quando o campo de ordem não está incluído no GROUP BY. Valores possíveis: first e last.

Uma medida de janela também suporta o seguinte campo opcional:

• deslocamento: Desloca a moldura da janela para trás ou para a frente ao longo do order campo num intervalo fixo. Use isto para medidas período após período, como mês a mês ou ano a ano. Para a sintaxe, as unidades suportadas e as restrições, consulte medidas da janela.

Também pode referenciar um parâmetro inteiro como o valor de range ou offset de uma medida de janela, para que o autor da chamada forneça o tamanho da janela no momento da execução da consulta. Veja Passar um tamanho de janela como parâmetro.

Como offset desloca a moldura da janela

Consulte a disponibilidade de funcionalidades da vista métrica para requisitos mínimos de computação e de versão da especificação YAML.

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

offset é independente de semiadditive. A escolha first ou last continua a controlar como a medida se colapsa quando order não está no GROUP BY da consulta.

Para melhores resultados, corresponda offset ao grão natural de order. Para dados mensais, offset: -12 month é preferível a offset: -365 day porque a aritmética de meses e anos respeita meses de duração variável e anos bissextos, enquanto a aritmética de day não o faz.

Incluir ou excluir a linha âncora

Consulte a disponibilidade de funcionalidades da vista métrica para requisitos mínimos de computação e de versão da especificação YAML.

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

O exemplo seguinte mostra como inclusive e exclusive afetam a janela rolante para a data 2025-01-05 de ancoragem com trailing 3 day.

Assuma 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 os seus valores:

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

Exemplo de medição de janela deslizante, móvel ou antecipada

O exemplo seguinte calcula uma contagem contínua de 7 dias dos clientes que efetuaram encomendas. Esta métrica acompanha as tendências de envolvimento dos clientes ao longo do tempo, mostrando quantos clientes distintos fizeram compras na semana anterior a 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, aplica-se a seguinte configuração:

• order: date especifica que o date campo ordena a janela.
• range: trailing 7 day define a janela como os 7 dias antes de cada data, excluindo a própria data.
• semiadditive: last devolve 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 período a período

O exemplo seguinte calcula o crescimento das vendas dia a dia comparando a receita de hoje (soma de todos os preços das encomendas) com a receita de ontem. Esta 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, aplica-se a seguinte configuração:

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

Exemplo de medida de janela ano a ano usando offset

O modificador offset é o elemento fundamental para as medidas de período sobre período. Defina uma cópia deslocada de uma medida base e depois compõe as duas para expressar deltas, razões ou taxas de crescimento diretamente na vista métrica.

O exemplo seguinte calcula o crescimento das vendas ano após ano comparando as vendas de cada mês com o mesmo mês do ano anterior. A medida deslocada utiliza offset: -12 month para recuar 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, aplica-se a seguinte configuração:

• monthly_sales é a medida base, somando as vendas do mês corrente.
• monthly_sales_py é a mesma medida deslocada 12 meses para trás utilizando offset: -12 month. Para janeiro de 2025, devolve o valor de janeiro de 2024.
• yoy_growth e yoy_growth_pct compor as duas medidas para expressar a variação absoluta e percentual. A utilização 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 seguinte calcula a receita acumulada de vendas desde o início do conjunto de dados até cada data. Este total contínuo mostra quanto da receita total foi gerada ao longo do tempo, sendo útil para acompanhar o progresso em direção aos objetivos anuais de receitas ou para analisar padrões de crescimento a 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, aplica-se a seguinte configuração:

• order: date ordena a janela por 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 retorna o valor acumulado mais recente quando date não está incluído na cláusula GROUP BY da consulta, em vez de somar os valores de todas as datas.

Exemplo de medida do período até à data

O exemplo seguinte calcula a receita de vendas acumulada do ano (YTD). Esta medida mostra a receita acumulada gerada desde 1 de janeiro de cada ano até à data atual, reiniciando-se no início de cada novo ano.

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, aplica-se a seguinte configuração:

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

Exemplo de medida semiaditiva

O exemplo seguinte calcula os saldos das contas, que não devem ser somados entre datas (não pode somar o saldo de segunda-feira ao saldo de terça-feira para obter o saldo total). Em vez disso, ao aglomerar dados ao longo de vários dias, a medida devolve o saldo mais recente. No entanto, a medida ainda pode ser somada entre clientes para mostrar o saldo total em todas as contas num dado 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, aplica-se a seguinte configuração:

• order: date ordena a janela por ordem cronológica.
• range: current restringe a janela a um único dia sem agregação entre dias.
• semiadditive: last devolve o saldo mais recente ao agregar vários dias.

Consultar uma medida de janela

Você pode consultar uma exibição métrica com uma medida de janela como qualquer outra exibição métrica. Uma medida de janela é calculada com base no campo order, pelo que uma consulta que desagrega os resultados ao longo do tempo tem de fazer referência a esse campo, seja diretamente ou por intermédio de um campo de hierarquia de datas definido para esse campo. Quando a consulta não faz referência ao campo de ordem, a semiadditive palavra-chave determina o valor devolvido, conforme descrito no exemplo da medida semiaditiva.

O exemplo seguinte agrupa uma medida de janela por state e por uma expressão de mês sobre o campo de ordenação 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

Agrupe por um campo de hierarquia de datas

Uma hierarquia de datas enrola o campo de ordens para grãos mais grossos, como semana, mês ou ano. Defina cada nível como um campo sobre o campo de ordem pelo nome, e não sobre a 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 da hierarquia devolve a medida com essa granularidade. Assumindo que o exemplo de período até à data é criado como ytd_metric_view, tal como no exemplo da medida de período até à data, a consulta seguinte devolve o valor YTD à data da última data de cada mês:

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

Capacidade de composição

As vistas métricas são componíveis. Podes construir novos campos e medidas que referenciam os existentes em vez de reescrever a lógica do zero. Isto reduz a duplicação e facilita a manutenção de definições métricas complexas.

A composabilidade funciona em dois níveis: dentro de uma única vista métrica e entre vistas métricas quando uma vista métrica é usada como fonte para outra.

A composabilidade suporta os seguintes padrões de referência:

• Campos anteriores em campos novos.
• Campos e medidas existentes em novas medidas.
• Campos a partir de vistas métricas usados como fonte em novos campos.
• Campos e medidas de visualizações métricas utilizados como origem para novas medidas.

Definir medidas com composabilidade

Na secção measures, pode referenciar medidas da vista métrica de origem ou medidas definidas anteriormente na mesma vista métrica. Esta abordagem melhora a consistência, a auditabilidade e a manutenção da sua camada semântica.

Exemplo: Valor médio de ordem (AOV)

O exemplo seguinte define o Valor Médio de Ordem (AOV) usando duas medidas atómicas: total_revenue (soma dos preços das encomendas) e order_count (número de ordens). 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 mudar (por exemplo, para excluir impostos), avg_order_value utiliza automaticamente a definição atualizada.

Composabilidade com lógica condicional

Você pode usar a capacidade de composição para criar proporções complexas, porcentagens 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 seguinte calcula a taxa de cumprimento: a percentagem de encomendas com estado 'F' (cumprido). A medida divide as encomendas cumpridas pelo total de encomendas.

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

Melhores práticas para composabilidade

1. Defina primeiro as medidas atómicas: Estabeleça as medidas fundamentais (SUM, COUNT, AVG) antes de definir as medidas que as referenciam.
2. Uso MEASURE() como referência: Use a MEASURE() função ao referenciar outra medida num expr. Não repitas a lógica de agregação manualmente. Por exemplo, evite SUM(a) / COUNT(b) se já existirem medidas para ambos os valores.
3. Dê prioridade à legibilidade: Componha 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, percentagens ou moeda) para ferramentas a jusante. Veja metadados do Agente em visualizações de métricas.

Recursos adicionais

• Vistas métricas de modelo
• Metadados do agente nas vistas métricas
• Materialização para visualizações métricas
• Referência da sintaxe YAML da vista métrica