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:

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)

Resolva matrizes e mapas na origem

Campos, medidas e junções operam sobre colunas planas e escalares. Se seus dados de origem tiverem colunas do tipo ARRAY ou MAP, converta-as em colunas simples na consulta source antes de referenciá-las em outras partes da visualização de métricas. 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, esteja a matriz na fonte principal ou em uma tabela à qual você faz junção. Veja Transformar tipos complexos de dados para o conjunto completo de funções de transformação.

No catálogo samples, nenhum conjunto de dados possui uma coluna de matriz, então os exemplos nesta seção usam uma exibição orders que tem uma matriz line_items de estruturas. Use o exemplo a seguir para criar uma visualização com um campo que é um array. Substitua catalog.schema pelo catálogo e pelo 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;

Converter uma matriz em linhas

Para analisar cada elemento do array como uma linha separada, use explode() na consulta source 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 de um mapa ou matriz.

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 padrão fan-out, modele a tabela destacada como uma one_to_many junção. Confira junções de 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 de origem mantém sua granularidade, e a coluna calculada fica disponível para os 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 a matriz antes que a visualização de métrica a 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 à qual você quer fazer junção, e não na fonte principal. Uma junção opera sobre as colunas planas, portanto expanda a matriz na source subconsulta da própria tabela associada antes de fazer a junção. Escreva a junção source como uma consulta SQL que achata ou agrega o array, depois junte nas colunas resultantes. Veja Junções em visualizações de 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 a matriz line_items de cada pedido em um escalar total_quantity antes da junção, para que a visão das métricas possa somá-lo por cliente sem duplicar as linhas de clientes:

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)

Em vez disso, para tratar cada elemento do array como sua própria linha na tabela resultante da junção, nivele o array com explode() na operação de junção source da mesma forma. Confira Mesclar uma matriz 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

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.

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 um relacionamento muitos-para-um. Em casos de muitos-para-muitos, o mecanismo seleciona a primeira linha correspondente da tabela de dimensões unida.

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 é de muitos para um (cada pedido tem exatamente um cliente), o que permite que o mecanismo otimize consultas que filtram campos da tabela unida.

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