Visualizações de métricas do modelo

As exibições de métrica criam uma camada semântica para seus dados, transformando tabelas e exibições em métricas de negócios padronizadas. Eles definem o que medir, como agregá-lo e como segmentá-lo. Como resultado, cada usuário em toda a organização relata o mesmo valor para o mesmo KPI, o que elimina relatórios inconsistentes e permite a análise flexível em todos os campos.

Os principais componentes definidos são fontes, junções, filtros, campos e medidas.

Para obter um exemplo completo com junções, campos, medidas e metadados do agente, consulte Tutorial: criar uma exibição de métrica com junções e modelagem de dados.

Componentes principais

Uma exibição de métrica consiste nos seguintes elementos:

Componente	Description	Example
Source	A tabela base, a exibição ou a consulta SQL que contém os dados.	samples.tpch.orders
Joins	Relações entre tabelas, visões e visões de métricas para enriquecer dados.	Unir a tabela orders com a tabela customers com base em customer_key
Filtros	Condições aplicadas aos dados de origem para definir o escopo.	status = 'completed' order_date > '2024-01-01'
Fields	Colunas usadas para agrupar, filtrar e agregar métricas. Inclui colunas categóricas e colunas numéricas não agregadas. Também chamado de dimensões.	Categoria do produto, mês do pedido, preço unitário
Medidas	Agregações de colunas de dados que geram métricas.	COUNT(o_orderkey) como Contagem de Pedidos, SUM(o_totalprice) como Receita Total

Definir uma origem

Você pode usar um ativo semelhante a uma tabela ou uma consulta SQL como a origem para sua exibição de métrica. Você deve ter pelo menos SELECT privilégios sobre qualquer ativo mencionado.

Um ativo semelhante a uma tabela é qualquer objeto do Catálogo do Unity que expõe um esquema tabular e dá suporte a consultas, incluindo tabelas, exibições, exibições materializadas, tabelas de streaming, tabelas estrangeiras, tabelas SELECT do sistema e exibições de métrica.

Usar um ativo semelhante a uma tabela como fonte

Para usar um ativo semelhante a uma tabela como fonte, especifique o nome totalmente qualificado. Por exemplo: samples.tpch.orders.

Usar uma visualização de métrica como fonte

Você pode usar uma exibição de métrica existente como a origem para uma nova exibição de métrica:

version: 1.1

source: views.examples.source_metric_view

fields:
  - name: Order month
    expr: '`Order Month`'

measures:
  - name: Latest order month
    expr: MAX(`Order month`)
  - name: Latest order year
    expr: "DATE_TRUNC('year', MEASURE(`Latest order month`))"

Ao usar uma exibição de métrica como origem, as mesmas regras de composição se aplicam a campos e medidas de referência. Consulte Modularidade.

Usar uma consulta SQL como origem

Para usar uma consulta SQL, escreva o texto da consulta diretamente no YAML:

version: 1.1

source: SELECT * FROM samples.tpch.orders o LEFT JOIN samples.tpch.customer c ON o.o_custkey
  = c.c_custkey

fields:
  - name: Order key
    expr: o_orderkey

measures:
  - name: Order Count
    expr: COUNT(o_orderkey)

Note

Ao usar uma consulta SQL como fonte com uma cláusula JOIN, defina restrições de chave primária e estrangeira nas tabelas subjacentes e use a opção RELY para obter o desempenho ideal da consulta. Consulte Declarar chave primária, chave estrangeira e restrições exclusivas e otimização de consulta usando a chave primária e restrições exclusivas.

Resolver arrays e mapas na fonte

Campos, medidas e uniões operam todos sobre colunas planas e escalares. Se seus dados de origem tiverem ARRAY ou MAP tipar colunas, resolva-as para colunas planas na source consulta antes de referencia-las em outro lugar na visualização métrica. Existem duas estratégias de transformação, dependendo se você quer uma linha por elemento do array ou um único valor por linha de origem. Ambos se aplicam seja o array na fonte de nível superior ou em uma tabela à qual você se junta. Veja Transformar tipos complexos de dados para o conjunto completo de funções de transformação.

Nenhum conjunto de dados no samples catálogo possui uma coluna de array, então os exemplos nesta seção usam uma orders visão que possui um line_items array de structs. Use o exemplo a seguir para criar uma visualização com um campo que é um array. Substitua catalog.schema pelo catálogo e esquema que você quer escrever. Você deve ter permissões para criar objetos nesse esquema.

CREATE OR REPLACE VIEW catalog.schema.orders AS
SELECT
  o.o_orderkey,
  o.o_custkey,
  o.o_orderdate,
  o.o_orderstatus,
  collect_list(named_struct(
    'product_id', l.l_partkey,
    'quantity', cast(l.l_quantity as int)
  )) AS line_items
FROM samples.tpch.orders o
JOIN samples.tpch.lineitem l ON o.o_orderkey = l.l_orderkey
GROUP BY o.o_orderkey, o.o_custkey, o.o_orderdate, o.o_orderstatus;

Achatar um array em linhas

Para analisar cada elemento do array como uma linha própria, use explode() na source consulta para desempacotar o array. Cada elemento se torna uma linha separada, e as outras colunas da linha de origem se repetem para cada elemento. Veja : Explodir elementos aninhados a partir de um mapa ou array.

O exemplo a seguir desempacota o line_items array de modo que cada item se torne uma linha:

version: 1.1
source: |
  SELECT o_orderkey, o_custkey, item.product_id, item.quantity
  FROM catalog.schema.orders
  LATERAL VIEW explode(line_items) AS item

fields:
  - name: Product
    expr: product_id

measures:
  - name: Total quantity
    expr: SUM(quantity)
  - name: Line item count
    expr: COUNT(1)

Explodir o array em o source multiplica as linhas de origem, então uma agregação como COUNT(1) conta elementos do array, não as linhas originais. Para também medir as linhas originais sem leque, modele a tabela explodida como uma one_to_many junção. Consulte junções um-para-muitos.

Agregar um array em um único valor

Para reduzir um array a um valor por linha de origem sem alterar a contagem de linhas, aplique uma função escalar de array na source consulta, como aggregate(), array_size(), ou reduce(). Cada linha fonte mantém seu grão, e a coluna computada está disponível para campos e medidas.

O exemplo a seguir calcula a contagem de itens e a quantidade total do line_items array por ordem:

version: 1.1
source: |
  SELECT o_orderkey, o_custkey,
    array_size(line_items) AS item_count,
    aggregate(line_items, 0, (acc, x) -> acc + x.quantity) AS total_quantity
  FROM catalog.schema.orders

measures:
  - name: Total quantity
    expr: SUM(total_quantity)
  - name: Average items per order
    expr: AVG(item_count)

Como a consulta de origem reduz o array antes que a visualização de métrica o processe, a fonte mantém uma linha por ordem e as medidas se agregam entre ordens como de costume.

Resolver um array em uma tabela unida

A mesma regra se aplica quando o array está em uma tabela que você quer entrar, não na fonte de nível superior. Uma junção opera em colunas planas, então resolve o array na própria source subconsulta da tabela unida antes da junção. Escreva a junção source como uma consulta SQL que achata ou agrega o array, depois junte nas colunas resultantes. Veja Joins em visualizações métricas.

O exemplo a seguir usa customer como fonte e une a orders visualização com cardinality: one_to_many. A junção source agrega o array de line_items cada ordem em um escalar total_quantity antes da junção, de modo que a visualização métrica pode somar por cliente sem duplicar linhas de cliente:

version: 1.1
source: samples.tpch.customer

joins:
  - name: orders
    source: |
      SELECT o_orderkey, o_custkey,
        aggregate(line_items, 0, (acc, x) -> acc + x.quantity) AS total_quantity
      FROM catalog.schema.orders
    on: orders.o_custkey = source.c_custkey
    cardinality: one_to_many

fields:
  - name: Customer name
    expr: c_name

measures:
  - name: Total quantity
    expr: SUM(orders.total_quantity)
  - name: Order count
    expr: COUNT(orders.o_orderkey)

Para tratar cada elemento do array como sua própria linha na tabela unida, achatar o array com explode() na junção source da mesma forma. Veja : Achatar um array em linhas.

Campos

Os campos, também chamados de dimensões, são colunas de exibição de métricas nas quais você pode usar SELECTWHEREe GROUP BY cláusulas no momento da consulta. Um campo pode ser uma coluna categórica, como região ou status, ou uma coluna numérica não agregada, como preço ou quantidade, que você pode agregar no momento da consulta. Cada expressão de campo deve retornar um valor escalar. Ele pode referenciar colunas dos dados de origem ou campos definidos anteriormente na exibição de métrica. Cada campo consiste em dois componentes:

• name: o alias da coluna
• expr: uma expressão SQL que faz referência aos dados de origem ou campos definidos anteriormente na exibição de métrica

Aviso

Os campos de exibição de métrica semelhante à cadeia de caracteres são sempre STRING, mesmo quando a coluna de origem é CHAR ou VARCHAR. Como CHAR(n) o preenchimento de espaço é perdido, as comparações podem retornar resultados diferentes. Por exemplo, column = 'COLLEGE' corresponde a um valor CHAR(10) na tabela de origem (que é preenchida com espaços), mas não no campo da visualização de métricas.

Medidas

Medidas são expressões que produzem resultados sem um nível de agregação pré-determinado. Eles devem ser expressos usando funções de agregação. Para fazer referência a uma medida em uma consulta, use a MEASURE função. As medidas podem fazer referência a colunas base nos dados de origem, campos definidos anteriormente ou medidas definidas anteriormente. Cada medida consiste nos seguintes componentes:

• name: o alias da medida
• expr: uma expressão SQL agregada que pode incluir funções de agregação do SQL

O exemplo a seguir demonstra padrões de medida comuns para analisar dados de ordem e receita. Esses exemplos usam a tabela de pedidos TPC-H, que contém dados de transação de vendas, incluindo preços de pedidos (o_totalprice), identificadores de clientes (o_custkey), chaves de pedido (o_orderkey), datas de pedidos (o_orderdate) e níveis de prioridade (o_orderpriority):

measures:
  # Simple count measure
  - name: Order Count
    expr: COUNT(1)

  # Sum aggregation measure
  - name: Total Revenue
    expr: SUM(o_totalprice)

  # Distinct count measure
  - name: Unique Customers
    expr: COUNT(DISTINCT o_custkey)

  # Calculated measure combining multiple aggregations
  - name: Average Order Value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)

  # Filtered measure with WHERE condition
  - name: High Priority Order Revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderpriority = '1-URGENT')

  # Measure using a field
  - name: Average Revenue per Month
    expr: SUM(o_totalprice) / COUNT(DISTINCT DATE_TRUNC('MONTH', o_orderdate))

Consulte funções de agregação para obter uma lista de funções de agregação.

Aplicar filtros

Um filtro se aplica a todas as consultas que fazem referência à exibição de métrica. Para definir um filtro na interface do usuário, consulte a Etapa 3: Definir um filtro.

Para definir um filtro na definição yaml, escreva uma expressão booliana. O exemplo a seguir mostra padrões de filtro comuns:

# Single condition
filter: o_orderdate > '2024-01-01'

# Multiple conditions
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

Trabalhar com junções

As exibições de métrica dão suporte a junções para enriquecer seus dados de origem com atributos de tabelas relacionadas. É possível modelar esquemas em estrela (tabela de fatos associada a tabelas de dimensões), esquemas em floco de neve (junções de dimensões em vários níveis) e relações um-para-muitos (expansão de fatos a partir de uma fonte dimensional). Para obter detalhes sobre tipos de junção, cardinalidade, padrões de esquema e restrições, consulte Junções em exibições de métrica.

Para definir junções na interface do usuário, consulte a Etapa 2: Adicionar uma junção. Para definir junções na definição yaml, use os padrões nas seções a seguir.

Note

Tabelas unidas não podem incluir ARRAY ou MAP digitar colunas. Para resolver arrays ou mapear para colunas planas antes de se juntar, veja Resolver arrays e mapas na fonte.

Esquemas de estrela modelo

Em um esquema de estrela, a source é a tabela de fatos e se conecta a uma ou mais tabelas de dimensão usando um LEFT OUTER JOIN. As exibições de métrica unem as tabelas de fatos e dimensões necessárias para a consulta específica, com base nos campos e medidas selecionados.

Especifique colunas de junção usando uma on cláusula (expressão booliana) ou uma using cláusula (nomes de coluna compartilhada). A junção deve seguir uma relação muitos-para-um. Em casos de relação muitos-para-muitos, o mecanismo seleciona a primeira linha correspondente da tabela de dimensão associada.

O exemplo a seguir une (tabela de fatos orders ) a customer (tabela de dimensões) e expõe os atributos do cliente como campos. A configuração rely.at_most_one_match: true declara que a junção é muitos-para-um (cada pedido tem exatamente um cliente), o que permite que o mecanismo otimize consultas que filtram por campos da tabela associada.

Aviso

Defina at_most_one_match: true somente quando a relação for muitos-para-um. Essa propriedade não é validada em runtime. Se a junção produzir um fan-out, as medidas retornarão resultados incorretos.

Consulte Otimizar junções com rely.

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey

fields:
  - name: Customer name
    expr: customer.c_name

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Sintaxe yaml e formatação

As definições de exibição de métrica seguem a sintaxe de notação YAML padrão. Consulte a referência de sintaxe YAML da exibição de métricas para a sintaxe e a formatação necessárias.

Práticas recomendadas

Use as seguintes diretrizes ao modelar exibições de métrica:

• Modelar medidas atômicas: comece definindo as medidas mais simples primeiro (por exemplo, SUM(revenue), ). COUNT(DISTINCT customer_id) Crie medidas complexas usando a capacidade de composição.
• Padronize os valores dos campos: Use transformações (como instruções CASE) para converter códigos do banco de dados em nomes de negócio claros (por exemplo, converter o status do pedido de 'O' para 'Aberto' e de 'F' para 'Atendido').
• Definir escopo com filtros: se uma exibição de métrica deve incluir apenas pedidos concluídos, defina esse filtro na exibição de métrica para que os usuários não possam incluir dados incompletos acidentalmente.
• Use a nomenclatura clara: os nomes de métrica devem ser reconhecíveis para usuários empresariais (por exemplo, "Valor de Tempo de Vida do Cliente" em vez de cltv_agg_measure).
• Campos de tempo separados: inclua campos de tempo granular (como "Data da Ordem") e campos de tempo truncados (como "Mês da Ordem" ou "Semana da Ordem") para habilitar a análise de nível de detalhes e tendência.

Recursos adicionais

• Junções em visualizações de métricas
• Técnicas avançadas para exibições de métrica
• 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