Técnicas avançadas para views de métricas

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érie temporal, como médias móveis, totais contínuos e mudanças de período a período.
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 view de métricas. Consulte views de métricas do modelo.

nota

Os exemplos desta página usam o dataset de exemplo TPC-H, que modela uma cadeia de suprimentos de atacado. Para mais informações sobre o dataset TPC-H, consulte tpch. Para um tutorial completo usando este dataset com views de métricas, consulte Tutorial: criar uma view de métricas com junções e modelagem de dados.

Medidas da janela

info

Experimental

Este recurso é Experimental.

As medidas de janela permitem definir medidas com agregações em janela, cumulativas ou semiaditivas em suas views de métricas. Elas 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 em YAML.

Adicionar uma medida de janela no editor

Na tab UI do editor de view de métricas, clique em + Window ao editar uma medida. A + Window está disponível nos modos Builder e Custom . As opções de window no editor correspondem aos campos YAML descritos em Definir uma medida de window.

Para obter mais informações sobre como criar e editar medidas, consulte Criar view de métricas.

Defina uma medida da 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, leading e all. Um intervalo trailing ou leading utiliza uma unidade de tempo em um campo de data ou timestamp order, como trailing 7 day, ou nenhuma unidade em uma coluna de número inteiro consecutivo order, como trailing 3. Para obter a sintaxe completa e descrições, consulte Valores range suportados. Para obter detalhes sobre os modificadores inclusive e exclusive em trailing e leading, consulte Incluir ou excluir a linha de âncora.
semiadditive : Especifica como agregar a medida quando o campo de ordem não está incluído no GROUP BY da query. 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 frente ao longo do campo order por uma quantidade fixa. Use um deslocamento datado, como -12 month, em um campo de data ou timestamp order para medidas entre períodos, como mês a mês ou ano a ano. Use um deslocamento numérico sem unidade, como -1, em uma coluna de número inteiro consecutivo order para comparar ao longo de um período comercial que não seja uma data de calendário. Para sintaxe, unidades compatíveis e restrições, consulte 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 um chamador passe o tamanho da janela no momento da query. Consulte Passar um tamanho de janela como parâmetro.

Como `offset` altera o quadro da janela

Consulte disponibilidade do recurso de view de métricas para requisitos mínimos de compute e versão de especificação YAML.

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 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)

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 escolha first ou last ainda controla como a medida é agrupada quando order não está na GROUP BY da query.

Para obter os 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 respeita meses de duração variável e anos bissextos, enquanto a aritmética day não.

Incluir ou excluir a linha âncora

Consulte disponibilidade do recurso de view de métricas para requisitos mínimos de compute e versão de especificação YAML.

Para intervalos trailing e leading, a palavra-chave opcional inclusive ou exclusive controla se o valor da janela da linha de ancoragem (por exemplo, hoje) faz parte da janela contínua:

Palavra-chave	Significado	Ancorar linha no intervalo?
`inclusive`	n unidades incluindo a linha âncora.	Sim
`exclusive` (padrão)	n unidades não incluindo a linha âncora.	Não

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

Assuma 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` (anchor)	`5`

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

Modificador	Datas na janela	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 final, em movimento ou inicial

O exemplo a seguir calcula uma contagem contínua de 7 dias de clientes que fizeram pedidos. Esta métrica rastreia 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, a seguinte configuração se aplica:

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.

Crie a view de métrica usando SQL

Para criar esta view de métricas fora do Catalog Explorer, envolva o YAML em CREATE OR REPLACE VIEW ... WITH METRICS LANGUAGE YAML AS e coloque a definição entre os delimitadores $$:

SQL
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
$$

As outras definições completas nesta página seguem o mesmo padrão.

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

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

Exemplo de medida de janela ano a ano usando `offset`

O modificador offset é o elemento construtivo para medidas de variação entre períodos. Defina uma cópia deslocada de uma medida base e, em seguida, componha as duas para expressar deltas, proporções 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 as ventas do mesmo mês do ano anterior. A medida defasada usa offset: -12 month para retroceder 12 meses no 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, a seguinte configuração se aplica:

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

Medidas de janela em uma coluna de índice numérico

Requer Databricks Runtime 19 ou acima e especificação YAML versão 1.1 ou acima.

Um offset datado, como -12 month, segue os passos ao longo de uma coluna de data ou timestamp. Uma coluna de data não se ajusta mais quando seu eixo de comparação é um período comercial que não é uma data de calendário. Semanas fiscais, semanas ISO e períodos contábeis 4-4-5 são todos exemplos. Em vez disso, ordene uma medida de janela em uma coluna de índice integral e aplique um offset ou range numérico sem unidade. Um deslocamento numérico faz aritmética de inteiros no índice, portanto offset: -1 significa a posição anterior na sequência, e range: trailing 3 significa as últimas três posições.

Um deslocamento ou intervalo numérico retorna o resultado correto apenas quando a coluna order atende a todos os seguintes requisitos. Apenas o primeiro requisito é validado no momento da query. Uma coluna que quebra qualquer uma das outras duas retorna números incorretos em vez de um erro, portanto, verifique-os você mesmo:

Integral : A coluna é um(a) TINYINT, SMALLINT, INT ou BIGINT. As colunas DATE, TIMESTAMP, DECIMAL, DOUBLE e STRING não são colunas de índice válidas. Para comparar ao longo de uma data, use um(a) offset datado(a) em vez disso. Consulte Como offset desloca a moldura da janela.
Monotônico e consecutivo (denso) : O valor aumenta exatamente 1 de cada período real para o próximo, inclusive através da fronteira de ano ou trimestre. Uma lacuna ou um valor repetido faz com que offset: -1 ignore ou conte duas vezes um período. Um rótulo raw, como um fiscal_week que Reset para 1 a cada ano, não é um índice válido por si só.
Correspondente ao grão de comparação : os passos de deslocamento ou intervalo no grão do índice. Em um índice de mês, offset: -1 é o mês anterior e range: trailing 3 são os últimos três meses. Para uma comparação mais ampla, como ano a ano, ordene uma medida separada em um índice de ano ou use uma medida de mesma posição em ciclo anterior. Não reutilize um índice mais refinado (mês) e agrupe. Consulte Mesma posição em um ciclo anterior (duas especificações de janela, sem índice).

Obter uma coluna de índice

Você pode nomear uma coluna de índice pré-computada da origem ou derivar uma na view de métricas. A receita depende do formato do calendário:

Forma do calendário	Índice recipe
Períodos uniformes por pai (12 meses por ano, 4 trimestres por ano)	`expr: year * 12 + month` (meses) ou `expr: year * 4 + quarter` (trimestres). Isso é exato e não precisa de nenhuma tabela extra.
Períodos variáveis por pai (ISO de 52 ou 53 semanas, 4-4-5 em granularidade semanal)	Use uma tabela de pesquisa de calendário que mapeia `(year, period)` para um número inteiro denso. Um `year * 53 + week` ingênuo sofre drift em anos de 52 semanas.
key de strings (`'YYYYPP'`, `'YYYY-Www'`)	Analise a string para números inteiros primeiro, depois aplique uma das receitas acima.

Forma do calendário	Índice recipe
Períodos uniformes por pai (12 meses por ano, 4 trimestres por ano)	`expr: year * 12 + month` (meses) ou `expr: year * 4 + quarter` (trimestres). Isso é exato e não precisa de nenhuma tabela extra.
Períodos variáveis por pai (ISO de 52 ou 53 semanas, 4-4-5 em granularidade semanal)	Use uma tabela de pesquisa de calendário que mapeia `(year, period)` para um número inteiro denso. Um `year * 53 + week` ingênuo sofre drift em anos de 52 semanas.
key de strings (`'YYYYPP'`, `'YYYY-Www'`)	Analise a string para números inteiros primeiro, depois aplique uma das receitas acima.

Alinhe as dimensões das quais o índice depende

Forneça uma especificação de ordenação range: all para cada campo da visualização de métricas a partir do qual o índice é calculado, como order_year e order_month para month_index = order_year * 12 + order_month. Isso se aplica independentemente de o índice ser derivado na view de métricas ou pré-calculado a montante como uma coluna simples. A especificação range: all faz com que esses campos sejam ignorados durante a construção da janela, conforme pretendido, quando uma query os agrupa ou filtra.

Estas especificações não são opcionais. Sem eles, uma query que agrupa em order_year ou order_month particiona a janela por esses campos, o que confina a moldura deslocada a um único período, e a medida de comparação retorna NULL.

Qualquer outro campo não recebe nenhuma especificação range: all. Um campo independente do índice, como region, agrupa normalmente, e a janela particiona por valor.

Comparação consecutiva ou janela deslizante (índice mais intervalo numérico)

Use um índice com um deslocamento numérico ou intervalo quando você quiser dizer "adjacente na sequência", como o período anterior, um período N contínuo ou o período até a data. Ordene pelo índice, aplique um deslocamento ou intervalo numérico e adicione uma especificação range: all para cada coluna de calendário da qual o índice depende. No exemplo a seguir, o índice depende de order_year e order_month:

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - name: order_year
    expr: YEAR(o_orderdate) # INT breakdown column
  - name: order_month
    expr: MONTH(o_orderdate) # INT breakdown column
  - name: month_index # consecutive monotonic index across years
    expr: order_year * 12 + order_month

measures:
  - name: monthly_sales
    expr: SUM(o_totalprice)
    window:
      - order: order_year # breakdown, so range: all keeps GROUP BY order_year working
        range: all
        semiadditive: last
      - order: order_month # breakdown
        range: all
        semiadditive: last
      - order: month_index # the axis you compare along
        range: current
        semiadditive: last

  - name: monthly_sales_prev # previous month: same specs plus a unitless offset of -1 on the index
    expr: SUM(o_totalprice)
    window:
      - order: order_year
        range: all
        semiadditive: last
      - order: order_month
        range: all
        semiadditive: last
      - order: month_index
        range: current
        offset: -1 # one position back, crosses the year boundary correctly
        semiadditive: last

  - name: sales_trailing_3mo # rolling 3 months: unitless range on the index
    expr: SUM(o_totalprice)
    window:
      - order: order_year
        range: all
        semiadditive: last
      - order: order_month
        range: all
        semiadditive: last
      - order: month_index
        range: trailing 3 # the three index positions before the current month
        semiadditive: last

  - name: mom_pct_change
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_prev))
      / NULLIF(MEASURE(monthly_sales_prev), 0) * 100

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

month_index é um índice monotônico consecutivo que aumenta em 1 a cada mês através dos limites do ano.
monthly_sales ordena no índice com range: current e fornece às colunas de detalhamento order_year e order_month uma especificação range: all para que o agrupamento por elas funcione.
monthly_sales_prev adiciona offset: -1 ao índice para retroceder um mês, o que cruza o limite do ano corretamente.
sales_trailing_3mo usa o intervalo sem unidade trailing 3 para somar três posições de índice. Como o índice é consecutivo, três posições equivalem sempre a três meses, sem envolvimento de aritmética de unidade de tempo. O intervalo é default para exclusive, portanto, cobre os três meses anteriores ao atual. Adicione inclusive para incluir o mês atual em vez disso.
mom_pct_change compõe as medidas base e deslocadas. O uso de NULLIF evita erros de divisão por zero quando o valor anterior é zero.

Faça a query da medida agrupando pelas colunas de detalhamento alinhadas, não pelo índice bruto:

SQL
SELECT
  order_year,
  order_month,
  MEASURE(monthly_sales),
  MEASURE(monthly_sales_prev),
  MEASURE(sales_trailing_3mo),
  MEASURE(mom_pct_change)
FROM catalog.schema.monthly_sales_mv
GROUP BY ALL

Mesma posição em um ciclo anterior (duas especificações de janela, sem índice)

Uma comparação como "o mesmo mês do ano passado" é alinhada por posição, não por distância absoluta, portanto, não precisa de uma coluna de índice. Use duas especificações de janela: uma desloca o ciclo pai e a outra mantém a posição interna.

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - name: order_year
    expr: YEAR(o_orderdate)
  - name: order_month
    expr: MONTH(o_orderdate)

measures:
  - name: monthly_sales
    expr: SUM(o_totalprice)

  - name: monthly_sales_py # same month, prior year
    expr: SUM(o_totalprice)
    window:
      - order: order_year # shift the year coordinate
        range: current
        offset: -1
        semiadditive: last
      - order: order_month # hold the month fixed
        range: current
        semiadditive: last

  - name: yoy_pct_change
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0) * 100

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

monthly_sales_py usa duas especificações de janela. A especificação order_year desloca a coordenada do ano para trás em um com offset: -1, e a especificação order_month mantém o mês fixo com range: current.
A comparação é alinhada por posição, portanto, não precisa de uma coluna de índice.
yoy_pct_change compõe as duas medidas para expressar a variação percentual.

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

O exemplo a seguir calcula a receita de vendas cumulativa desde o início do dataset até cada data. Este total acumulado mostra quanta receita total foi gerada ao longo do tempo, útil para o acompanhamento do progresso em relação às metas anuais de receita ou para a análise de padrões de crescimento de 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, a seguinte configuração se aplica:

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 na GROUP BY da query, em vez de somar em todas as datas.

Exemplo de medida acumulada até a data

O exemplo a seguir calcula a receita de vendas acumulada no ano (YTD). Esta medida mostra a receita cumulativa gerada a partir de 1º de janeiro de cada ano até a data atual, redefinindo-se 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: 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 campo date e outra para limitar a soma ao ano current.
O campo year restringe a soma cumulativa para que ela se Reset 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 no campo date pelo nome, e não na coluna subjacente o_orderdate, assim, as queries podem agrupar esta medida por eles. Consulte Agrupar por um campo de hierarquia de data.

Exemplo de medida semiaditiva

O exemplo a seguir calcula os saldos da account, que não devem ser somados em diferentes datas (não é possível 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 clientes para mostrar o saldo total em 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, a seguinte configuração se aplica:

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 em vários dias.

nota

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

Query uma medida de janela

Você pode query uma view de métricas com uma medida de janela como qualquer outra view de métricas. Uma medida de janela é computada junto com seu campo order, então uma query que divide os resultados ao longo do tempo deve referenciar esse campo, seja diretamente ou através de um campo de hierarquia de data definido nele. Quando a query não referencia o campo de ordem, a palavra-chave semiadditive determina o valor retornado, conforme descrito em Exemplo de medida semiaditiva.

O exemplo a seguir agrupa uma medida de janela por state e por uma expressão de mês sobre o campo de ordenação date:

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

Agrupar por um campo de hierarquia de data

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

YAML
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 retorna a medida nesse nível de detalhe. Supondo que o exemplo de período até a data seja criado como ytd_metric_view, assim como no exemplo de medida de período até a data, a seguinte query retorna o valor YTD a partir da última data de cada mês:

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

atenção

Definir um nível de hierarquia na coluna de origem subjacente, como DATE_TRUNC('MONTH', o_orderdate), quebra seu Link para o campo de ordem date, mesmo que as expressões pareçam equivalentes. Agrupar uma medida de janela por um campo desse tipo retorna resultados incorretos.

Componibilidade

View 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 complexas de métricas mais fáceis de manter.

A composabilidade 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 Composability oferece suporte aos seguintes padrões de referência:

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

Definir medidas com componibilidade

Na seção measures, você pode fazer referência a medidas da view de métricas de origem ou a medidas definidas anteriormente na mesma view de métricas. Essa abordagem melhora a consistência, a capacidade de auditoria 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. Estes formam os blocos de construção.	`SUM(o_totalprice)`
Composto	Uma expressão que combina matematicamente uma ou mais outras medidas usando a função `MEASURE()`.	`MEASURE(total_revenue) / MEASURE(order_count)`

Tipo de medida	Descrição	Exemplo
Atômico	Uma agregação simples e direta em uma coluna de origem. Estes formam os blocos de construção.	`SUM(o_totalprice)`
Composto	Uma expressão que combina matematicamente uma ou mais outras 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 do pedido) 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 total_revenue mudar (por exemplo, para excluir impostos), avg_order_value usará automaticamente a definição atualizada.

Componibilidade com lógica condicional

É possível usar a componibilidade 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 a seguir calcula a taxa de cumprimento: a porcentagem de pedidos com status 'F' (cumpridos). A medida divide os pedidos cumpridos 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

Práticas recomendadas para componibilidade

Defina as medidas atômicas primeiro : Estabeleça as medidas fundamentais (SUM, COUNT, AVG) antes de definir as medidas que as referenciam.
Use MEASURE() para referências : use a função MEASURE() ao fazer referência a outra medida em um expr. Evite repetir a lógica de agregação manualmente. Por exemplo, evite SUM(a) / COUNT(b) se medidas para ambos os valores já existirem.
Priorize a 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.
Adicionar metadados semânticos : Use metadados semânticos para formatar medidas compostas (por exemplo, porcentagens ou moeda) para ferramentas downstream. Consulte Metadados de agente em views de métricas.

Medidas da janela​

Adicionar uma medida de janela no editor​

Defina uma medida da janela​

Como offset altera o quadro da janela​

Incluir ou excluir a linha âncora​

Exemplo de medida de janela final, em movimento ou inicial​

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

Exemplo de medida de janela ano a ano usando offset​

Medidas de janela em uma coluna de índice numérico​

Obter uma coluna de índice​

Alinhe as dimensões das quais o índice depende​

Comparação consecutiva ou janela deslizante (índice mais intervalo numérico)​

Mesma posição em um ciclo anterior (duas especificações de janela, sem índice)​

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

Exemplo de medida acumulada até a data​

Exemplo de medida semiaditiva​

Query uma medida de janela​

Agrupar por um campo de hierarquia de data​

Componibilidade​

Definir medidas com componibilidade​

Exemplo: Valor médio do pedido (AOV)​

Componibilidade com lógica condicional​

Exemplo: Taxa de cumprimento​

Práticas recomendadas para componibilidade​

Mais recursos​

Medidas da janela

Adicionar uma medida de janela no editor

Defina uma medida da janela

Como `offset` altera o quadro da janela

Incluir ou excluir a linha âncora

Exemplo de medida de janela final, em movimento ou inicial

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

Exemplo de medida de janela ano a ano usando `offset`

Medidas de janela em uma coluna de índice numérico

Obter uma coluna de índice

Alinhe as dimensões das quais o índice depende

Comparação consecutiva ou janela deslizante (índice mais intervalo numérico)

Mesma posição em um ciclo anterior (duas especificações de janela, sem índice)

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

Exemplo de medida acumulada até a data

Exemplo de medida semiaditiva

Query uma medida de janela

Agrupar por um campo de hierarquia de data

Componibilidade

Definir medidas com componibilidade

Exemplo: Valor médio do pedido (AOV)

Componibilidade com lógica condicional

Exemplo: Taxa de cumprimento

Práticas recomendadas para componibilidade

Mais recursos