Pular para o conteúdo principal

tutorial: criar uma view de métricas com join e modelagem de dados

Neste tutorial, você cria uma view de métricas de analítica de vendas no dataset TPC-H. Ao final, você terá uma view de métricas que:

  • Une pedidos e clientes em várias tabelas usando um esquema em floco de neve.
  • Define campos (também chamados de dimensões) para atributos de tempo, geografia e ordem.
  • Calcula medidas simples e complexas, incluindo taxas, agregações filtradas e medidas de janela.
  • Usa a componibilidade para criar métricas complexas a partir de medidas mais simples.
  • Define um parâmetro para aplicar uma taxa de desconto no momento da query.
  • Inclui metadados do agente para dashboards e ferramentas de AI.

Se é novo em views de métricas, comece com Criar uma view de métricas para aprender o básico. Este tutorial estende essa base com a complexidade do mundo real.

Requisitos

Para completar este tutorial, você deve ter:

  • Um Workspace habilitado para o Unity Catalog.
  • Um SQL Warehouse ou recurso de compute executando o Databricks Runtime 17.3 ou acima.

Para a lista completa de privilégios necessários para criar uma view de métricas, consulte Pré-requisitos.

nota

A criação de uma view de métricas tem suporte no Databricks Runtime 16.4 e acima. Este tutorial usa recursos que exigem o Databricks Runtime 17.3 ou acima, e alguns passos exigem um tempo de execução posterior. Para o Runtime mínimo para cada recurso, consulte Disponibilidade do recurso de view de métricas.

Modelo de dados

O dataset TPC-H modela uma cadeia de suprimentos atacadista. Este tutorial usa três tabelas unidas em um esquema em floco de neve:

  • orders joins para customer em o_custkey = c_custkey
  • customer joins para nation em c_nationkey = n_nationkey

Tabela

Função

Colunas key

orders

Tabela de fatos (transações de pedido)

o_orderkey, o_custkey, o_totalprice, o_orderdate, o_orderstatus

customer

Tabela de dimensões (detalhes do cliente)

c_custkey, c_name, c_mktsegment, c_nationkey

nation

Tabela de dimensões (referência de país ou região)

n_nationkey, n_name, n_regionkey

Tabela

Função

Colunas key

orders

Tabela de fatos (transações de pedido)

o_orderkey, o_custkey, o_totalprice, o_orderdate, o_orderstatus

customer

Tabela de dimensões (detalhes do cliente)

c_custkey, c_name, c_mktsegment, c_nationkey

nation

Tabela de dimensões (referência de país ou região)

n_nationkey, n_name, n_regionkey

o passo 1: Criar a view de métricas e abrir o editor

Você pode construir esta view de métricas na interface do usuário do Catalog Explorer, gerá-la com Genie Code ou escrever a definição YAML completa diretamente. Todos os três métodos resultam em uma única definição YAML que modela a view de métricas. Em cada passo que se segue, selecione a tab **Catalog Explorer UI** ou **editor YAML** para seguir seu método preferido. Se você usa o editor YAML, o código de exemplo em cada passo é a parte da definição YAML que corresponde ao que você constrói naquele passo.

nota

Os exemplos YAML neste tutorial usam a palavra-chave fields. Ao criar uma view de métricas no editor de baixo código, o YAML que ela gera usa a palavra-chave dimensions equivalente em vez disso. Consulte Campos.

Se você não estiver familiarizado com a interface do usuário para criar views de métricas, consulte Criar uma view de métricas.

Para criar a view de métrica, no Catalog Explorer:

  1. Buscar por samples.tpch.orders.
  2. Clique no nome da tabela.
  3. Clique em Criar > View de métricas e nomeie a view.

Para os passos detalhados de criação, consulte Criar uma view de métricas. Quando o editor abrir, use a tab UI para construir interativamente, ou clique no botão <> para editar a definição YAML diretamente.

Passo 2: Configurar a view de métricas

Defina uma versão e uma descrição para a view de métricas. O version determina a versão da especificação YAML, e o comment documenta a finalidade da view de métricas, que aparece no Catalog Explorer. A Databricks gerencia a versão.

A versão é definida para você. Para adicionar ou editar a descrição depois de salvar a view de métricas:

  1. No Catalog Explorer, procure pela view de métricas e clique no nome dela.
  2. Clique em Descrição e, em seguida, insira uma descrição da view de métricas. É possível usar a descrição de exemplo exibida na tab editor YAML .

Este texto corresponde ao campo comment na definição YAML. Para mais formas de editar uma view de métricas, consulte Editar uma view de métricas.

Passo 3: Defina a origem e os joins

Defina a tabela de origem primária e faça join com as tabelas relacionadas:

  • source define a tabela de fatos (pedidos) como a granularidade.
  • joins traz dados do cliente usando uma relação de muitos para um.
  • O join nation aninhado demonstra um padrão de esquema floco de neve, unindo-se por meio de customer para alcançar dados geográficos, onde a nação é uma subdimensão do cliente.

Este exemplo adiciona dois joins, ambos Muitos-para-um , para modelar o esquema snowflake.

Para adicionar o join customer:

  1. No editor, clique em Join no canto superior direito para abrir a caixa de diálogo Adicionar join .
  2. Pesquise samples.tpch.customer, clique no nome da tabela e, em seguida, clique em Adicionar .
  3. Defina a condição de join como o_custkey = c_custkey.
  4. Em Cardinalidade da Junção , selecione Muitos-para-um . Para orientação sobre como escolher uma cardinalidade, consulte Cardinalidade de join.

Em seguida, adicione o join aninhado nation. Repita os passos do customer join, unindo samples.tpch.nation em c_nationkey = n_nationkey. Aninhar o join sob customer modela o país como uma subdimensão do cliente.

Para os passos completos do diálogo de join, consulte passo 2: Adicionar um join.

Passo 4: Definir um filtro

Uma filter limita os dados de origem e se aplica a todas as queries na view de métricas. Este tutorial limita a view de métricas a dados recentes.

Para definir o filtro:

  1. No editor, clique em Ícone de filtro. Filtrar no canto superior direito.
  2. Use os menus suspensos para definir a **Coluna** o_orderdatecomo, o **Operador** como >= e o **Valor** 1995-01-01como.

Para saber mais sobre filtros, consulte Passo 3: Defina um filtro.

Passo 5: Definir campos

Campos são os atributos que os usuários agrupam e filtram. Um campo pode ser uma coluna categórica (como região ou status) ou uma coluna numérica não agregada (como idade ou quantidade) que os usuários agregam no momento da query.

Metadados de agente

Cada campo e medida neste tutorial inclui propriedades de metadados de agente que melhoram a forma como sua view de métricas funciona com dashboards e ferramentas de AI:

  • display_name: Um rótulo legível que aparece em visualizações em vez do nome técnico da coluna.
  • synonyms: Nomes alternativos que ajudam ferramentas de AI como o Genie a descobrir campos e medidas por meio de queries em linguagem natural.
  • format: Como os valores são exibidos em superfícies downstream, como dashboards, Notebooks e resultados de query SQL, por exemplo, como moeda, número ou porcentagem.

Essas propriedades são opcionais, mas recomendadas. As definições de campos e medidas nos seguintes passos os incluem diretamente.

Definições de campo

Este tutorial adiciona:

  • **Campos de order_date order_monthtempo:**, e order_year em várias granularidades para suportar diferentes necessidades de análise.
  • **Campos transformados:** order_status order_prioritye, que usam CASE e SPLIT para converter códigos-fonte em rótulos legíveis.
  • Campos de join:, customer_name market_segmente,customer_nation que fazem referência a tabelas join usando o nome do join. Colunas de junção aninhadas usam notação de ponto encadeada, como customer.nation.n_name, para percorrer o esquema snowflake.

O editor adiciona todas as colunas de origem à tab automaticamente. Edite, renomeie, remova e adicione campos para que a view de métricas defina exatamente o seguinte. Para cada campo, clique no nome para editá-lo ou clique Ícone de adicionar ou ícone de mais em **Adicionar** para criá-lo e defina a expressão no modo **Construtor** ou **Personalizado**. Defina o **Nome de exibição** e os **Sinônimos** para cada campo, conforme mostrado.

  1. order_date: No o_orderdate modo **Construtor**, selecione a coluna. Defina o nome de exibição como Order Date.

  2. order_month : No modo Personalizado , insira DATE_TRUNC('MONTH', order_date). Defina o nome de exibição como Order Month.

  3. order_year : No modo Personalizado , insira YEAR(order_date). Defina o nome de exibição como Order Year.

  4. order_status : No modo Custom , insira a seguinte expressão. Defina o nome de exibição como Order Status e os sinônimos como status, fulfillment status.

    SQL
    CASE o_orderstatus
    WHEN 'O' THEN 'Open'
    WHEN 'P' THEN 'Processing'
    WHEN 'F' THEN 'Fulfilled'
    END
  5. **order_priority**: No modo **Personalizado**,SPLIT(o_orderpriority, '-')[0] insira. Defina o nome de exibição como Priority.

  6. customer_name : No modo Builder , selecione a coluna c_name da tabela customer unida. Defina o nome de exibição como Customer Name.

  7. market_segment : No modo Builder , selecione a coluna c_mktsegment da tabela customer unida. Defina o nome de exibição como Market Segment e os sinônimos como segment, industry.

  8. customer_nation : No modo Personalizado , insira customer.nation.n_name para fazer referência ao join nation aninhado. Defina o nome de exibição como Country e os sinônimos como nation, country.

Para ver todos os passos do campo, consulte Passo 4: Adicionar campos.

Passo 6: Definir parâmetros

Os parâmetros permitem passar valores para a view de métricas ao consultá-la, de modo que uma única definição pode atender a muitas variantes de query. Este tutorial adiciona um parâmetro discount que uma medida posterior usa para calcular a receita com desconto. O parâmetro tem um default de 0, de modo que as queries que não passam um valor retornam a receita sem desconto. Para saber mais sobre parâmetros, consulte Usar parâmetros com view de métricas.

No cabeçalho do editor, clique em Adicionar parâmetro . Insira discount como o nome, em seguida, insira um valor default de 0 e selecione o tipo de dados double.

Passo 7: Definir medidas

Medidas são os cálculos que os usuários desejam analisar. Primeiro, defina medidas atômicas e, em seguida, use a capacidade de composição para criar métricas complexas que referenciem medidas definidas anteriormente com a função MEASURE(). Defina display_name, format e synonyms para cada medida, conforme descrito em Metadados do agente. Este tutorial adiciona:

  • Medidas atômicas: order_count, total_revenue e unique_customers, as agregações simples que formam os blocos de construção.
  • Medidas compostas: avg_order_value e revenue_per_customer, que fazem referência a medidas definidas anteriormente com MEASURE() em vez de duplicar a lógica de agregação. Se total_revenue for alterado, essas medidas usarão automaticamente a definição atualizada. Consulte Componibilidade.
  • Medidas filtradas: open_order_revenue e fulfilled_order_revenue, que usam FILTER (WHERE ...) para criar métricas condicionais sem campos separados.
  • Medida parametrizada: discounted_revenue, que referencia o parâmetro discount para aplicar uma taxa de desconto. Consulte Usar parâmetros com views de métricas.
  • **Medida t7d_customers de janela:**, que calcula uma contagem contínua de 7 dias de clientes únicos. Consulte Medidas de janela para mais padrões de medida de janela.

O editor adiciona uma medida COUNT(*) de amostra automaticamente. Edite ou remova-o e adicione medidas para que a view de métricas defina exatamente o seguinte. Para cada medida, clique em Ícone de adicionar ou ícone de mais Adicionar e, em seguida, defina a expressão no modo Construtor ou Personalizado . Defina o Nome de exibição , o Formato e os Sinônimos conforme mostrado. Use duas casas decimais para formatos de moeda e zero casas decimais para formatos de número.

  1. order_count : No modo Builder , selecione a agregação Contagem distinta em o_orderkey. Defina o nome de exibição como Order Count, formato como Número .
  2. total_revenue : No modo Builder , selecione a agregação Sum em o_totalprice. Defina o nome de Total Revenue exibição como, o formato como **Moeda (USD)**, os sinônimos revenue salescomo,.
  3. discounted_revenue : No modo Personalizado , insira SUM(o_totalprice * (1 - discount)). Defina o nome de exibição como Discounted Revenue, o formato como Currency (USD) .
  4. unique_customers : No modo Construtor , selecione a agregação de Contagem distinta em o_custkey. Defina o nome de exibição como Unique Customers, o formato como Número .
  5. avg_order_value : No modo Custom , insira MEASURE(total_revenue) / MEASURE(order_count). Defina nome de exibição como Avg Order Value, formato como Currency (USD) , sinônimos como AOV.
  6. revenue_per_customer : No modo Personalizado , insira MEASURE(total_revenue) / MEASURE(unique_customers). Defina o nome de exibição como Revenue per Customer, o formato como Currency (USD) .
  7. open_order_revenue : No modo Personalizado , insira SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O'). Defina o nome de exibição como Open Order Revenue, o formato como Moeda (USD) e os sinônimos como backlog.
  8. fulfilled_order_revenue : No modo Personalizado , insira SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'F'). Defina o nome de exibição como Fulfilled Revenue, formate como Moeda (USD) .
  9. t7d_customers : No modo Custom , insira COUNT(DISTINCT o_custkey). Em seguida, clique em + Window e configure uma janela ordenada por order_date com intervalo trailing 7 day e agregação semiaditiva last. Defina nome de exibição como 7-Day Rolling Customers, formato como Number .

Para ver todos os passos da medida, consulte Passo 5: Adicionar medidas.

Revise a definição completa

Após concluir os passos acima, sua view de métricas tem a seguinte definição completa:

Visualize a definição YAML completa

YAML
version: 1.1

parameters:
- name: discount
data_type: double
default: 0

source: SELECT * FROM samples.tpch.orders

joins:
- name: customer
source: samples.tpch.customer
'on': o_custkey = c_custkey
joins:
- name: nation
source: samples.tpch.nation
'on': c_nationkey = n_nationkey

filter: o_orderdate >= '1995-01-01'

comment: |-
Sales analytics metric view for order performance analysis.
Joins orders with customers and geography.
Owner: Analytics Team
Last updated: 2025-01-15

fields:
- name: order_date
expr: o_orderdate
display_name: Order Date
- name: order_month
expr: "DATE_TRUNC('MONTH', order_date)"
display_name: Order Month
- name: order_year
expr: YEAR(order_date)
display_name: Order Year
- name: order_status
expr: |-
CASE o_orderstatus
WHEN 'O' THEN 'Open'
WHEN 'P' THEN 'Processing'
WHEN 'F' THEN 'Fulfilled'
END
display_name: Order Status
synonyms:
- status
- fulfillment status
- name: order_priority
expr: "SPLIT(o_orderpriority, '-')[0]"
display_name: Priority
- name: customer_name
expr: customer.c_name
display_name: Customer Name
- name: market_segment
expr: customer.c_mktsegment
display_name: Market Segment
synonyms:
- segment
- industry
- name: customer_nation
expr: customer.nation.n_name
display_name: Country
synonyms:
- nation
- country

measures:
- name: order_count
expr: COUNT(DISTINCT o_orderkey)
display_name: Order Count
format:
type: number
decimal_places:
type: exact
places: 0
abbreviation: compact
- name: total_revenue
expr: SUM(o_totalprice)
display_name: Total Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- revenue
- sales
- name: discounted_revenue
expr: SUM(o_totalprice * (1 - discount))
display_name: Discounted Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: unique_customers
expr: COUNT(DISTINCT o_custkey)
display_name: Unique Customers
format:
type: number
decimal_places:
type: exact
places: 0
abbreviation: compact
- name: avg_order_value
expr: MEASURE(total_revenue) / MEASURE(order_count)
display_name: Avg Order Value
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- AOV
- name: revenue_per_customer
expr: MEASURE(total_revenue) / MEASURE(unique_customers)
display_name: Revenue per Customer
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: open_order_revenue
expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
display_name: Open Order Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- backlog
- name: fulfilled_order_revenue
expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'F')
display_name: Fulfilled Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: t7d_customers
expr: COUNT(DISTINCT o_custkey)
window:
- order: order_date
semiadditive: last
range: trailing 7 day
display_name: 7-Day Rolling Customers
format:
type: number
decimal_places:
type: exact
places: 0

Crie a view de métrica usando SQL

Se você estiver criando esta definição fora do Catalog Explorer, execute o seguinte SQL para criar a view de métricas:

SQL
CREATE OR REPLACE VIEW catalog.schema.tpch_sales_analytics
WITH METRICS
LANGUAGE YAML
AS $$
version: 1.1

parameters:
- name: discount
data_type: double
default: 0

source: SELECT * FROM samples.tpch.orders

joins:
- name: customer
source: samples.tpch.customer
'on': o_custkey = c_custkey
joins:
- name: nation
source: samples.tpch.nation
'on': c_nationkey = n_nationkey

filter: o_orderdate >= '1995-01-01'

comment: |-
Sales analytics metric view for order performance analysis.
Joins orders with customers and geography.
Owner: Analytics Team
Last updated: 2025-01-15

fields:
- name: order_date
expr: o_orderdate
display_name: Order Date
- name: order_month
expr: "DATE_TRUNC('MONTH', order_date)"
display_name: Order Month
- name: order_year
expr: YEAR(order_date)
display_name: Order Year
- name: order_status
expr: |-
CASE o_orderstatus
WHEN 'O' THEN 'Open'
WHEN 'P' THEN 'Processing'
WHEN 'F' THEN 'Fulfilled'
END
display_name: Order Status
synonyms:
- status
- fulfillment status
- name: order_priority
expr: "SPLIT(o_orderpriority, '-')[0]"
display_name: Priority
- name: customer_name
expr: customer.c_name
display_name: Customer Name
- name: market_segment
expr: customer.c_mktsegment
display_name: Market Segment
synonyms:
- segment
- industry
- name: customer_nation
expr: customer.nation.n_name
display_name: Country
synonyms:
- nation
- country

measures:
- name: order_count
expr: COUNT(DISTINCT o_orderkey)
display_name: Order Count
format:
type: number
decimal_places:
type: exact
places: 0
abbreviation: compact
- name: total_revenue
expr: SUM(o_totalprice)
display_name: Total Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- revenue
- sales
- name: discounted_revenue
expr: SUM(o_totalprice * (1 - discount))
display_name: Discounted Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: unique_customers
expr: COUNT(DISTINCT o_custkey)
display_name: Unique Customers
format:
type: number
decimal_places:
type: exact
places: 0
abbreviation: compact
- name: avg_order_value
expr: MEASURE(total_revenue) / MEASURE(order_count)
display_name: Avg Order Value
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- AOV
- name: revenue_per_customer
expr: MEASURE(total_revenue) / MEASURE(unique_customers)
display_name: Revenue per Customer
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: open_order_revenue
expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
display_name: Open Order Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
synonyms:
- backlog
- name: fulfilled_order_revenue
expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'F')
display_name: Fulfilled Revenue
format:
type: currency
currency_code: USD
decimal_places:
type: exact
places: 2
abbreviation: compact
- name: t7d_customers
expr: COUNT(DISTINCT o_custkey)
window:
- order: order_date
semiadditive: last
range: trailing 7 day
display_name: 7-Day Rolling Customers
format:
type: number
decimal_places:
type: exact
places: 0
$$;

Para outras formas de criar uma view de métricas, consulte Criar uma view de métricas.

Passo 8: Query a view de métricas

Query a view de métricas usando sintaxe amigável aos negócios. A função MEASURE() agrega uma medida no nível de detalhe dos campos que você seleciona.

Agrupar medidas por dimensão.

Este exemplo agrega medidas em vários campos. Ele retorna a receita total, a contagem de pedidos e o valor médio do pedido por país do cliente e segmento de mercado, classificados pela maior receita primeiro:

SQL
SELECT
customer_nation,
market_segment,
MEASURE(total_revenue) AS total_revenue,
MEASURE(order_count) AS order_count,
MEASURE(avg_order_value) AS avg_order_value
FROM catalog.schema.tpch_sales_analytics
GROUP BY customer_nation, market_segment
ORDER BY total_revenue DESC;

Analise uma tendência mensal

Este exemplo combina um campo de tempo com medidas para acompanhar uma tendência. Ele retorna a receita total e a receita de pedidos em aberto (pendências) por mês e status do pedido:

SQL
SELECT
order_month,
order_status,
MEASURE(total_revenue) AS total_revenue,
MEASURE(open_order_revenue) AS open_order_revenue
FROM catalog.schema.tpch_sales_analytics
GROUP BY order_month, order_status
ORDER BY order_month;

Passe um valor de parâmetro

Como a view de métricas define um parâmetro, você pode chamá-la como uma função com valor de tabela e passar um valor no momento da query. A query a seguir aplica um desconto de 10%. Como discount tem um default de 0, as queries que omitem o argumento retornam receita sem desconto:

SQL
SELECT
customer_nation,
MEASURE(total_revenue) AS total_revenue,
MEASURE(discounted_revenue) AS discounted_revenue
FROM catalog.schema.tpch_sales_analytics(discount => 0.1)
GROUP BY customer_nation
ORDER BY discounted_revenue DESC;

O que você aprendeu

Você construiu uma view de métricas que demonstra:

Recurso

Exemplo

Snowflake schema joins

Pedidos para cliente para país (joins aninhados de muitos para um)

Campos de tempo

Granularidade de data, mês, ano

Campos transformados

CASE instruções, SPLIT funções

Medidas simples

COUNT, SUM

Componibilidade

avg_order_value e revenue_per_customer referenciam medidas definidas anteriormente usando MEASURE()

Medidas filtradas

FILTER (WHERE ...) para agregações condicionais

Medidas da Janela

Contagem contínua de clientes de 7 dias usando trailing 7 day

Parâmetros

discount parâmetro aplicado na medida discounted_revenue

Metadados do agente

display_name, format, synonyms em campos e medidas

Recurso

Exemplo

Snowflake schema joins

Pedidos para cliente para país (joins aninhados de muitos para um)

Campos de tempo

Granularidade de data, mês, ano

Campos transformados

CASE instruções, SPLIT funções

Medidas simples

COUNT, SUM

Componibilidade

avg_order_value e revenue_per_customer referenciam medidas definidas anteriormente usando MEASURE()

Medidas filtradas

FILTER (WHERE ...) para agregações condicionais

Medidas da Janela

Contagem contínua de clientes de 7 dias usando trailing 7 day

Parâmetros

discount parâmetro aplicado na medida discounted_revenue

Metadados do agente

display_name, format, synonyms em campos e medidas

Mais recursos