Vistas métricas de modelo

As vistas métricas criam uma camada semântica para os seus dados, transformando tabelas e vistas em métricas de negócio padronizadas. Eles definem o que medir, como agregar e como segmentar. Como resultado, todos os utilizadores da organização reportam o mesmo valor para o mesmo KPI, o que elimina relatórios inconsistentes e permite análises flexíveis em qualquer campo.

Os componentes principais que defines são fontes, joins, filtros, campos e medidas.

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

Componentes centrais

Uma vista métrica consiste nos seguintes elementos:

Componente	Description	Example
Source	A tabela base, vista ou consulta SQL que contém os dados.	samples.tpch.orders
Junta-se	Relações entre tabelas, vistas e vistas métricas para enriquecer dados.	Juntar orders tabela com customers tabela em customer_key
Filtros	Aplicavam-se condições aos dados de origem para definir o âmbito.	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 da encomenda, preço unitário
Medidas	Agregações de colunas que produzem métricas.	COUNT(o_orderkey) como Contagem de Encomendas, SUM(o_totalprice) como Receita Total

Definir uma fonte

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

Um ativo semelhante a tabela é qualquer objeto do Unity Catalog que expõe um esquema tabular e suporta SELECT consultas, incluindo tabelas, vistas, vistas materializadas, tabelas de fluxo, tabelas estrangeiras, tabelas de sistema e vistas métricas.

Use um asset 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.

Use uma vista métrica como fonte

Pode usar uma vista métrica existente como fonte para uma nova vista 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 vista métrica como fonte, aplicam-se as mesmas regras de composição para referenciar campos e medidas. Consulte Composabilidade.

Usar uma consulta SQL como fonte

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 JOIN cláusula, defina restrições de chave primária e estrangeira nas tabelas subjacentes e use a RELY opção para um desempenho ótimo da consulta. Veja Declarar chave primária, chave estrangeira e restrições únicas e Otimização de Consultas usando chave primária e restrições únicas.

Resolver arrays e mapas na fonte

Campos, medidas e uniões operam todos sobre colunas planas e escalares. Se os seus dados de origem tiverem ARRAY ou MAP tiverem colunas de tipo, resolva-as para colunas planas na source consulta antes de as referenciar noutro local da vista métrica. Existem duas estratégias de transformação, dependendo se pretende uma linha por elemento do array ou um único valor por linha de origem. Ambos se aplicam quer o array esteja na fonte de topo ou numa tabela à qual se junta. Consulte Transformar tipos complexos de dados para o conjunto completo de funções de transformação.

Nenhum conjunto de dados no samples catálogo tem uma coluna de array, por isso os exemplos nesta secção usam uma orders vista com um line_items array de structs. Use o seguinte exemplo para criar uma vista com um campo que é um array. Substitui catalog.schema pelo catálogo e esquema onde queres escrever. Tens de 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() a source consulta para desempacotar o array. Cada elemento torna-se uma linha separada, e as outras colunas da linha de origem repetem-se para cada elemento. Veja : Explodir elementos aninhados a partir de um mapa ou array.

O exemplo seguinte desembala 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 multiplica source as linhas de origem, por isso 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. Ver uniões de um para muitos.

Agregar um array num único valor

Para reduzir um array para 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 o seu grão, e a coluna calculada está disponível para campos e medidas.

O exemplo seguinte 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 de a visualização da métrica o processar, a fonte mantém uma linha por ordem e mede o agregam entre ordens como habitualmente.

Resolver um array numa tabela unida

A mesma regra aplica-se quando o array está numa tabela que queres juntar, e não na fonte de topo. Uma junção opera em colunas planas, por isso resolve o array na própria subconsulta da source tabela unida antes da junção. Escreve a junção source como uma consulta SQL que achata ou agrega o array, depois junta nas colunas resultantes. Veja Junções em vistas métricas.

O exemplo seguinte usa customer como fonte e junta a orders vista com cardinality: one_to_many. A junção source agrega o array de line_items cada ordem num escalar total_quantity antes da junção, para que a vista métrica possa somar por cliente sem duplicar as linhas do 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 uma linha própria na tabela junta, achatar o array com explode() na junção source da mesma forma. Veja : Achatar um array em linhas.

Campos

Os campos, também chamados dimensões, são colunas de vistas de métricas que pode utilizar nas cláusulas SELECT, WHERE e GROUP BY ao consultar. Um campo pode ser uma coluna categórica, como região ou estado, ou uma coluna numérica não agregada, como preço ou quantidade, que pode agregar no momento da consulta. Cada expressão de campo deve devolver um valor escalar. Pode referenciar colunas dos dados de origem ou campos definidos anteriormente na vista métrica. Cada campo consiste em dois componentes:

• name: O pseudónimo da coluna
• expr: Uma expressão SQL que faz referência aos dados de origem ou aos campos previamente definidos na vista métrica

Warning

Campos métricos de visualização semelhantes a strings são sempre STRING, mesmo quando a coluna de origem é CHAR ou VARCHAR. Como se perde o preenchimento com espaços em CHAR(n), as comparações podem produzir resultados diferentes. Por exemplo, column = 'COLLEGE' corresponde a um CHAR(10) valor na tabela de origem (que é preenchido por espaço), mas não no campo de visualização métrica.

Medidas

As medidas são expressões que produzem resultados sem um nível pré-determinado de agregação. Devem ser expressos utilizando funções agregadas. Para referenciar uma medida numa consulta, use a MEASURE função. As medidas podem referenciar colunas base nos dados de origem, campos definidos anteriormente ou medidas definidas anteriormente. Cada medida consiste nas seguintes componentes:

• name: O pseudónimo da medida
• expr: Uma expressão SQL agregada que pode incluir funções agregadas SQL

O exemplo seguinte demonstra padrões comuns de medição para analisar dados de encomendas e receitas. Estes exemplos utilizam a tabela de encomendas TPC-H, que contém dados de transações de vendas, incluindo preços de encomenda (o_totalprice), identificadores de clientes (o_custkey), chaves de encomenda (o_orderkey), datas de encomenda (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 Agregar funções para obter uma lista de funções agregadas.

Aplicar filtros

Um filtro aplica-se a todas as consultas que referenciam a vista métrica. Para definir um filtro na interface, veja o Passo 3: Defina um filtro.

Para definir um filtro na definição YAML, escreva uma expressão Booleana. O exemplo seguinte mostra padrões comuns de filtros:

# 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'

Trabalho com junções

As visualizações métricas suportam junções para enriquecer os seus dados de origem com atributos de tabelas relacionadas. Pode modelar esquemas em estrela (tabela de factos associada a tabelas de dimensões), esquemas em floco de neve (junções de dimensões multinível) e relações de um para muitos (expansão da tabela de factos a partir de uma fonte dimensional). Para detalhes sobre tipos de junção, cardinalidade, padrões de esquema e restrições, veja Joins nas vistas métricas.

Para definir junções na interface de utilizador, consulte Passo 2: Adicionar uma junção. Para definir junções na definição em YAML, use os padrões descritos nas secções seguintes.

Note

Tabelas unidas não podem incluir ARRAY nem MAP digitar colunas. Para resolver arrays ou mapear para colunas planas antes de se juntarem, veja Resolver arrays and maps na fonte.

Esquemas de estrela modelo

Em um esquema em estrela, o source é a tabela de fatos e se une a uma ou mais tabelas de dimensão usando um LEFT OUTER JOINarquivo . As vistas métricas juntam as tabelas de factos 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 booleana) ou uma using cláusula (nomes de colunas partilhados). A associação tem de seguir uma relação de muitos para um. Nos casos de muitos-para-muitos, o mecanismo seleciona a primeira linha correspondente da tabela de dimensões associada.

O exemplo seguinte liga orders (tabela de factos) a customer (tabela de dimensões) e expõe os atributos do cliente como campos. Definir rely.at_most_one_match: true declara que a associação é muitos para um (cada encomenda tem exatamente um cliente), o que permite ao motor de consulta otimizar consultas que filtram por campos da tabela associada.

Warning

Defina at_most_one_match: true apenas quando a relação for de muitos para um. Esta propriedade não é validada em tempo de execução. Se a junção produzir um fan-out, as medidas devolvem 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 e formatação YAML

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

Melhores práticas

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

• Modele medidas atómicas: Comece por definir primeiro as medidas mais simples (por exemplo, SUM(revenue), COUNT(DISTINCT customer_id)). Construa medidas complexas usando a composabilidade.
• Padronizar os valores dos campos: Use transformações (como CASE sentenças) para converter códigos de base de dados em nomes claros de negócio (por exemplo, converter o estado da ordem 'O' para 'Aberto' e 'F' para 'Cumprido').
• Defina o âmbito com filtros: Se uma vista métrica deve incluir apenas ordens concluídas, defina esse filtro na vista métrica para que os utilizadores não possam incluir acidentalmente dados incompletos.
• Use nomes claros: Os nomes das métricas devem ser reconhecíveis pelos utilizadores empresariais (por exemplo, "Customer Lifetime Value" em vez de cltv_agg_measure).
• Campos de tempo separados: Inclua campos de tempo granulares (como "Data da Encomenda") e campos de tempo truncados (como "Mês da Encomenda" ou "Semana da Encomenda") para permitir tanto a análise a nível de detalhe como a de tendências.

Recursos adicionais

• Junções em vistas métricas
• Técnicas avançadas para vistas métricas
• Metadados do agente nas vistas métricas
• Materialização para visualizações métricas
• Referência da sintaxe YAML da vista métrica