Técnicas avançadas para visualização de Métis

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

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

Esta página pressupõe familiaridade com os conceitos básicos de modelagem view de métricas. Veja a visualização de métricas do modelo.

nota

Os exemplos nesta página utilizam o dataset de amostra TPC-H, que modela uma cadeia de suprimentos de atacado. Para obter mais informações sobre o dataset TPC-H, consulte tpch. Para um tutorial completo usando este dataset com a visualização de métricas, consulte o tutorial: Criar uma view de métricas completa com join.

Medidas da janela

info

Experimental

Este recurso é experimental.

Medidas de janela permitem definir medidas com agregações em janela, cumulativas ou semiaditivas nas suas views de métricas, com suporte a cálculos como médias móveis, variações entre períodos e totais acumulados.

Defina uma medida de janela.

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

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

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

• semiaditiva : Especifica como agregar a medida quando o campo de ordem não estiver incluído na GROUP BY da consulta. Os valores possíveis são first e last.

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

• Deslocamento : Desloca a moldura da janela para trás ou para frente ao longo do campo order em um intervalo fixo. Utilize isto para medidas entre períodos, tais como mês a mês ou ano a ano. Para sintaxe, unidades compatíveis e restrições, consulte Medidas da janela.

Como offset move o quadro da janela

Requer Databricks Runtime 18.1 e versão 1.1 ou mais recente do YAML. Consulte requisitos de versão.

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

intervalo	Quadro sem deslocamento	Quadro com offset: k
current	[t, t]	[t + k, t + k]
cumulative	(-infinity, t]	(-infinity, t + k]
trailing N	[t - N, t)	[t + k - N, t + k)
leading N	(t, t + N]	(t + k, t + k + N]
all	partição inteira	partição inteira (inalterada)

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

Para obter melhores resultados, combine offset ao veio natural de order. Para dados mensais, offset: -12 month é preferível a offset: -365 day porque a aritmética de mês e ano respeita meses de duração variável e anos bissextos, enquanto a aritmética de day não.

Incluir ou excluir a linha âncora

Requer Databricks Runtime 18.1 e versão 1.1 ou mais recente do YAML. Consulte requisitos de versão.

Para os intervalos de 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 deslizante:

Palavra-chave	Significado	A linha âncora está no intervalo?
inclusive	n unidades incluindo a linha âncora.	Sim
exclusive (padrão)	n unidades, sem incluir a linha âncora.	Não

O exemplo a seguir mostra como inclusive e exclusive afetam a janela deslizante para a data de âncora 2025-01-05 com trailing 3 day.

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

Data	Valor
2025-01-02	1
2025-01-03	4
2025-01-04	2
2025-01-05 (âncora)	5

Cada modificador seleciona três dias de linhas relativos à âncora e soma seus valores:

Modificador	Datas no período	Valores	Soma
trailing 3 day inclusive	01-03, 01-04, 01-05	4 + 2 + 5	11
trailing 3 day exclusive	01-02, 01-03, 01-04	1 + 4 + 2	7

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

Exemplo de medida de janela inicial, móvel ou posterior

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

YAML

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 campo date 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.

Exemplo de medida de janela período a período

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

YAML

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:

• São utilizadas duas medidas de janela: uma para calcular o total de vendas do dia anterior e outra para o dia atual.
• Uma terceira medida calcula a variação percentual (crescimento) entre o dia atual e o dia anterior.

Exemplo de medida de janela ano a ano usando offset

O modificador offset é o elemento fundamental para medidas de período sobre período. Defina uma cópia deslocada de uma medida base, então componha as duas para expressar deltas, taxas ou taxas de crescimento diretamente na view de métricas.

O exemplo a seguir calcula o crescimento de ventas ano a ano, comparando as ventas de cada mês com o mesmo mês do ano anterior. A medida deslocada usa offset: -12 month para analisar os últimos 12 meses ao longo do campo month.

YAML

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 para o mês atual.
• monthly_sales_py é a mesma medida retrocedida em 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 de NULLIF evita erros de divisão por zero quando o valor do ano anterior for zero.

Exemplo de medida de total cumulativo (acumulado)

O exemplo a seguir calcula a receita acumulada de vendas desde o início do dataset até cada data. Este total acumulado mostra a receita total gerada ao longo do tempo, sendo útil para acompanhar o progresso em direção às metas de receita anual ou para analisar padrões de crescimento a longo prazo.

YAML

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 cronologicamente.
• range: cumulative define a janela como todos os dados desde o início do dataset até e incluindo cada data.
• semiadditive: last retorna o valor cumulativo mais recente quando date não está incluído no GROUP BY da query, em vez de somar em todas as datas.

Exemplo de medida acumulada no período

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

YAML

version: 1.1

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

fields:
  - name: date
    expr: o_orderdate
  - name: year
    expr: DATE_TRUNC('year', o_orderdate)
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:

• Duas especificações de janela são usadas: uma para a soma cumulativa sobre o campo date e outra para limitar a soma ao ano current.
• O campo year restringe a soma cumulativa para que ela seja redefinida no início de cada novo ano.

Exemplo de medida semiaditiva

O exemplo a seguir calcula saldos account , que não devem ser somados entre datas (não é possível somar o saldo de segunda-feira ao saldo de terça-feira para obter o saldo total). Em vez disso, ao agregar dados de vários dias, a métrica retorna o saldo mais recente. No entanto, a métrica ainda pode ser somada entre os clientes para mostrar o saldo total de todas as contas em um determinado dia.

YAML

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 cronologicamente.
• range: current restringe a janela a um único dia sem agregação entre dias.
• semiadditive: last retorna o saldo mais recente ao agregar ao longo de vários dias.

nota

Esta medida da janela ainda soma para todos os clientes para obter o saldo geral por dia.

Consultar uma medida de janela

Você pode consultar uma view de métricas com uma medida de janela, assim como em qualquer outra view de métricas. O exemplo a seguir consulta uma view de métricas:

SQL

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

Composabilidade

Views de métricas são componíveis. Você pode criar novos campos e medidas que fazem referência aos existentes em vez de reescrever a lógica do zero. Isso reduz a duplicação e facilita a manutenção de definições complexas de métricas.

A componibilidade funciona em dois níveis: dentro de uma única view de métricas, e entre views de métricas quando uma view de métricas é usada como fonte para outra.

A capacidade de composição suporta os seguintes padrões de referência:

• Campos anteriores em novos campos.
• Campos e medidas anteriores em novas medidas.
• Campos de views de métricas usados como fonte em novos campos
• Campos e medidas de view de métricas usados como fonte em novas medidas.

Defina medidas com composibilidade

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

Tipo de medida	Descrição	Exemplo
Atômico	Uma agregação simples e direta em uma coluna de origem. Esses são os elementos básicos.	SUM(o_totalprice)
Composto	Uma expressão que combina matematicamente uma ou mais medidas usando a função MEASURE() .	MEASURE(total_revenue) / MEASURE(order_count)

Exemplo: Valor Médio do Pedido (AOV)

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

YAML

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 definição de total_revenue mudar (por exemplo, para excluir impostos), avg_order_value usa automaticamente a definição atualizada.

Composibilidade com lógica condicional

Você pode usar a capacidade de composição para criar índices complexos, 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 Atendimento

O exemplo a seguir calcula a taxa de atendimento: a porcentagem de pedidos com status 'F' (atendidos). A métrica divide os pedidos atendidos pelo total de pedidos.

YAML

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 composibilidade

1. Defina primeiro as medidas atômicas : Estabeleça as medidas fundamentais (SUM, COUNT, AVG) antes de definir as medidas que as referenciam.
2. Use MEASURE() para referências : Use a função MEASURE() ao referenciar outra medida em um expr. Não repita a lógica de agregação manualmente. Por exemplo, evite SUM(a) / COUNT(b) se já existirem medidas para ambos os valores.
3. Priorize a legibilidade : Elabore as medidas utilizando 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 subsequentes. Consulte os metadados do agente na visualização de métricas.

Próximos passos

• Vista do modelo
• Metadados do agente na visualização de métricas
• Materialização para visão de Métis
• métricas view referência de sintaxe YAML