Criar view de métricas

O Catalog Explorer fornece uma interface visual para criar views de métricas. Você define campos e medidas interativamente, sem escrever uma definição YAML.

Esta página explica como criar uma view de métricas no UI do Catalog Explorer. Para um exemplo mais complexo com joins e medidas avançadas, consulte Tutorial: criar uma view de métricas com joins e modelagem de dados.

Pré-requisitos

Antes de criar uma view de métricas, verifique se você tem as seguintes permissões:

• SELECT privilégios no ativo semelhante a tabela ou query SQL usado como origem.
• Privilégios CREATE TABLE e USE SCHEMA no esquema onde você deseja criar a view de métricas.
• Privilégio USE CATALOG no catálogo pai.
• CAN USE permissão em um SQL Warehouse ou outro recurso de compute executando o Databricks Runtime 17.3 ou acima.

Um administrador de metastore ou proprietário do catálogo pode conceder todos esses privilégios. Um proprietário de esquema ou usuário com privilégio MANAGE pode conceder privilégios USE SCHEMA e CREATE TABLE no esquema.

nota

A criação de uma view de métricas tem suporte no Databricks Runtime 16.4 e acima. Esta página usa recursos que exigem Databricks Runtime 17.3 ou superior, portanto 17.3 é o mínimo para o exemplo. Recursos YAML individuais podem exigir um Runtime posterior. Para o runtime mínimo de cada recurso, consulte Disponibilidade de recursos do view de métricas.

Criar uma view de métricas

Crie uma view de métricas no Catalog Explorer usando um dos métodos a seguir:

• **Editor de UI**: na **tab** de UI, defina campos e medidas interativamente, sem escrever código.
• **Editor YAML**: clique no <> botão para editar a definição diretamente. Para a sintaxe, consulte a referência de sintaxe YAML da view de métricas. Você também pode usar uma definição YAML em uma instrução SQL para criar uma view de métricas. Para o exemplo completo em YAML e SQL, consulte Definir uma view de métricas em SQL ou YAML.
• Genie Code : abra o Genie Code no botão no canto superior direito e descreva o que você deseja em linguagem natural. Consulte Usar o Genie Code.

As seguintes etapas usam a tab IU e a tabela samples.tpch.orders, disponível em cada workspace, para construir uma view de métricas de analítica de ventas de exemplo. A view de métricas concluída corresponde à definição em Definir uma view de métricas em SQL ou YAML. Para saber mais sobre este dataset, consulte Datasets de exemplo.

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

1. Clique em Catalog na barra lateral do Workspace.
2. Use a barra de pesquisa para encontrar samples.tpch.orders e, em seguida, clique no nome da tabela.
3. Clique em Criar > View de métricas . Na caixa de diálogo Criar view de métricas , insira um nome, selecione um catálogo e um destino de esquema e clique em Criar .

O editor abre na tab **UI**. O editor adiciona automaticamente todas as colunas de origem à tab **Fields** e adiciona uma COUNT(*) medida de exemplo.

O passo 2: Adicionar um join

O exemplo join a tabela customer para que os atributos do cliente estejam disponíveis como campos. Para adicionar o join, clique no botão join no canto superior direito do editor:

1. Para a origem para join, selecione samples.tpch.customer e clique em Adicionar .
2. Insira customer como o nome do join .
3. Use as listas suspensas para definir a condição de join como source.o_custkey = customer.c_custkey. Para adicionar mais de uma coluna de join, clique em + key de join . Para definir uma condição diferente de igualdade, clique em Expressão e refine a condição.
4. Em Cardinalidade da Junção , selecione Muitos-para-um . Para orientação sobre como escolher uma cardinalidade, consulte Cardinalidade de join.
5. Selecione No máximo uma correspondência em desempenho da query. Cada pedido corresponde a no máximo um cliente, portanto, essa otimização é segura e define at_most_one_match: true na definição YAML.
6. Click join .
7. Na caixa de diálogo Adicionar campos , clique em Adicionar todas as colunas para importar dinamicamente todas as colunas da tabela de origem. Se você quiser adicionar colunas individuais, em vez disso, Pule este passo. Campos do objeto com join aparecem no menu suspenso com campos da origem.

Joins combinam a tabela de origem com outras tabelas ou queries. Para conceitos de modelagem de join, incluindo esquemas em estrela e Snowflake, e padrões YAML, consulte Trabalhar com joins.

Passo 3: Definir um filtro

A definição YAML completa, mais adiante nesta página, inclui um filtro que limita a view de métricas a pedidos feitos após 1º de janeiro de 1990.

Insira expressões com Builder ou Custom

Ao definir um filtro, campo ou medida, a expressão é configurada usando uma das duas opções na seção **Expressão**:

• Construtor : Selecione nos menus suspensos com reconhecimento de contexto, e o editor compõe a expressão SQL para você.
• Personalizado : Insira a expressão SQL diretamente.

Os passos seguintes utilizam o Construtor para filtragem, transformações e agregações de colunas simples, e Personalizado para expressões que o Construtor não consegue compor, como instruções CASE e medidas compostas.

Para definir o filtro:

1. Clique em Filtro no canto superior direito do editor de view de métricas.
2. Defina a expressão de filtro:
   • Em **Builder**, selecione a source.o_orderdate **Coluna**, o **Operador** Greater than e o 1990-01-01**Valor**.
   • Em **Personalizado**, escreva a expressão SQL.source.o_orderdate > '1990-01-01'

Um filtro se aplica a todas as queries que referenciam a view de métricas. Para conceitos de modelagem de filtro e padrões YAML, consulte Aplicar filtros.

Passo 4: Adicionar campos

Ao definir um filtro, campo ou medida, a expressão é configurada usando uma das duas opções na seção **Expressão**:

• Construtor : Selecione em menus suspensos com reconhecimento de contexto, e o editor compõe a expressão SQL para você. As opções disponíveis mudam com base no tipo de coluna e nos valores.
• Personalizado : Insira a expressão SQL diretamente.

Os passos a seguir alternam entre as duas opções com base na complexidade de cada expressão. Use Builder para transformações e agregações de coluna simples, e mude para Personalizado para expressões que o Builder não pode compor, como instruções CASE e medidas compostas.

O exemplo define três campos: duas colunas transformadas da origem e uma coluna da tabela customer unida. Campos, também chamados dimensões, comportam-se como colunas de tabela regulares. Um campo pode ser uma coluna categórica usada para agrupamento e filtragem, ou uma coluna numérica não agregada que você pode agregar no momento da query. Para saber mais sobre modelagem de campos, consulte Campos.

O editor adiciona todas as colunas de origem à tab automaticamente. Para corresponder ao exemplo, remova as colunas de que não precisa para que apenas source.o_orderdate, source.o_orderstatus e customer.c_mktsegment permaneçam.

Para remover um campo:

1. Clique na guia tab .
2. Clique na caixa de seleção à esquerda do nome do campo para selecionar os campos que deseja remover.
3. Clique em Excluir .

Para excluir campos individuais, use a à direita do nome do campo.

Ao editar um campo, você também pode adicionar metadados:

• Nome de exibição : um rótulo descritivo.
• **Comentário**: uma descrição do campo.
• Sinônimos : nomes alternativos que ajudam as ferramentas de AI a descobrir o campo. Consulte Sinônimos.
• Formato : formatação de dados personalizada que controla como os valores são exibidos. A formatação só está disponível para colunas numéricas, de data e data/hora. Consulte especificações de formato.
• Tags controladas : tags controladas para classificação e governança.

Para definir cada campo, clique no seu nome na tab Campos, crie sua expressão e adicione um comentário opcional. Para executar a transformação e view o resultado, clique em Visualizar .

1. Mês do Pedido : Clique em Construtor . Então, selecione source.o_orderdate e aplique uma transformação de mês para produzir DATE_TRUNC('MONTH', source.o_orderdate). Adicione o comentário Month of order.

2. Status do Pedido : Clique em Personalizado . Em seguida, adicione o comentário Status of order e insira a seguinte expressão:

   SQL

   CASE
     WHEN source.o_orderstatus = 'O' THEN 'Open'
     WHEN source.o_orderstatus = 'P' THEN 'Processing'
     WHEN source.o_orderstatus = 'F' THEN 'Fulfilled'
   END

3. Segmento de Mercado : No Builder , selecione a coluna customer.c_mktsegment da tabela unida customer. Adicione o comentário Customer market segment.

Passo 5: Adicionar medidas

O exemplo define três medidas. Medidas são expressões agregadas que produzem métricas de negócios, como receita total ou contagem de pedidos. O editor adiciona uma medida COUNT(*) automaticamente; você pode editá-la ou removê-la.

Ao editar uma medida, é possível também adicionar um Nome de exibição , Comentário , Sinônimos , Formato e Tags governadas , os mesmos metadados disponíveis para campos.

Para adicionar cada medida, na tab Medidas clique em + , construa a sua expressão e adicione um comentário opcional. Para executar a agregação e visualizar o resultado, clique em Pré-visualizar . Ao adicionar uma medida, as sugestões do Genie aparecem na parte superior do painel do editor de medidas; clique em uma sugestão para criar essa medida.

1. Contagem de Pedidos : em Builder , selecione a agregação Count para produzir COUNT(1). Adicione o comentário Total number of orders.
2. Receita Total : Em Builder , selecione source.o_totalprice e a agregação Sum para produzir SUM(source.o_totalprice). Adicione o comentário Sum of all order prices.
3. Receita Total por Cliente : Em Personalizado , insira SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey). Adicione o comentário Average revenue per unique customer.

Para adicionar uma medida de janela para cálculos de séries temporais, como médias móveis ou totais de execução, clique em + Janela ao editar a medida. Consulte Medidas de janela.

Passo 6: Salvar a view de métricas

Clique em Salvar . A view de métricas concluída corresponde à definição em Definir uma view de métricas em SQL ou YAML.

Defina uma view de métricas em SQL ou YAML

Em vez de criar uma view de métricas na UI, você pode defini-la diretamente em YAML, ou em SQL usando a declaração CREATE VIEW com a cláusula WITH METRICS. A seguir está a definição completa da view de métricas de exemplo. É uma view filtrada de samples.tpch.orders associada a samples.tpch.customer, com campos para mês do pedido, status do pedido e segmento de mercado do cliente, e medidas para contagem de pedidos, receita total e receita por cliente.

nota

Estes exemplos usam a palavra-chave fields. Ao criar uma view de métricas no editor de baixo código, o YAML que ele gera usa a palavra-chave dimensions equivalente. Consulte Campos.

Definição YAML

Para definir a view de métricas diretamente no YAML, use a seguinte definição:

Visualizar a definição YAML

YAML

version: 1.1
comment: 'Orders KPIs for sales analysis'
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

filter: source.o_orderdate > '1990-01-01'

fields:
  - name: Order Month
    expr: DATE_TRUNC('MONTH', source.o_orderdate)
    comment: 'Month of order'

  - name: Order Status
    expr: |-
      CASE
        WHEN source.o_orderstatus = 'O' THEN 'Open'
        WHEN source.o_orderstatus = 'P' THEN 'Processing'
        WHEN source.o_orderstatus = 'F' THEN 'Fulfilled'
      END
    comment: 'Status of order'

  - name: Market Segment
    expr: customer.c_mktsegment
    comment: 'Customer market segment'

measures:
  - name: Order Count
    expr: COUNT(1)
    comment: 'Total number of orders'

  - name: Total Revenue
    expr: SUM(source.o_totalprice)
    comment: 'Sum of all order prices'

  - name: Total Revenue per Customer
    expr: SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey)
    comment: 'Average revenue per unique customer'

Para detalhes completos da sintaxe YAML, consulte Referência de sintaxe YAML da view de métricas.

Comando SQL

Para criar a view de métricas em SQL, envolva a definição YAML em uma instrução CREATE VIEW com a cláusula WITH METRICS e coloque o YAML entre os delimitadores $$:

Visualizar o comando SQL

SQL

CREATE OR REPLACE VIEW orders_metric_view WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1
  comment: "Orders KPIs for sales analysis"
  source: samples.tpch.orders

  joins:
    - name: customer
      source: samples.tpch.customer
      'on': source.o_custkey = customer.c_custkey
      rely:
        at_most_one_match: true

  filter: source.o_orderdate > '1990-01-01'

  fields:
    - name: Order Month
      expr: DATE_TRUNC('MONTH', source.o_orderdate)
      comment: "Month of order"

    - name: Order Status
      expr: |-
        CASE
          WHEN source.o_orderstatus = 'O' THEN 'Open'
          WHEN source.o_orderstatus = 'P' THEN 'Processing'
          WHEN source.o_orderstatus = 'F' THEN 'Fulfilled'
        END
      comment: "Status of order"

    - name: Market Segment
      expr: customer.c_mktsegment
      comment: "Customer market segment"

  measures:
    - name: Order Count
      expr: COUNT(1)
      comment: "Total number of orders"

    - name: Total Revenue
      expr: SUM(source.o_totalprice)
      comment: "Sum of all order prices"

    - name: Total Revenue per Customer
      expr: SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey)
      comment: "Average revenue per unique customer"
$$

Importar campos e medidas em massa com curingas

Aplica-se a: Databricks Runtime 18.2 e acima com a especificação YAML 1.1

Em vez de listar cada campo, você pode usar um curinga em um expr para importar todas as colunas da origem ou de uma tabela unida. Isso é útil quando você deseja que a view de métricas exponha todas as colunas de um ativo upstream. Omita name em um curinga, porque o Databricks deriva cada nome de coluna da origem. Você pode misturar curingas com campos e medidas definidos explicitamente.

A seguinte definição importa todos os campos da origem, exceto um, adiciona um campo da tabela customer unida e define uma medida explícita:

YAML

version: 1.1
source: samples.tpch.orders

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

fields:
  - expr: source.* EXCEPT (o_comment)
  - name: Market Segment
    expr: customer.c_mktsegment

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

Para a sintaxe curinga completa, incluindo a importação de todas as colunas de uma tabela unida (customer.*), expansão de struct e resolução de conflitos de nome, consulte Importar campos e medidas em massa com curingas.

Use o Genie Code

O Genie Code é um assistente de IA que se abre no botão no canto superior direito do editor. Descreva o que deseja em linguagem natural, e o Genie Code atualiza a definição da view de métricas para você. O Genie Code é sensível ao contexto: na tab **UI** ele atualiza o editor para você, e no editor YAML ele insere YAML.

Para adicionar uma única medida a uma view de métricas existente, descreva-a:

prompt

Diga ao Genie Code (modo Agente) para fazer isso por você:

add an average sales per customer measure

Para construir uma view de métricas completa a partir de uma descrição em linguagem natural, descreva-a ao Genie Code. O resultado é uma definição similar ao exemplo nesta página; os nomes de campo e os comentários exatos podem variar.

prompt

Diga ao Genie Code (modo Agente) para fazer isso por você:

Create a metric view on samples.tpch.orders joined to samples.tpch.customer on o_custkey = c_custkey. Add a field for order month by truncating the order date to the month, a field for order status that maps 'O' to Open, 'P' to Processing, and 'F' to Fulfilled, and a field for the customer market segment. Add measures for the total number of orders, the total revenue as the sum of order price, and the total revenue per unique customer. Filter to orders placed after January 1, 1990.

Mais recursos

Após criar uma view de métricas, use os seguintes recursos para query, modelar e gerenciar seu trabalho.

• Query views de métricas: query views de métricas de editores SQL, notebooks, painéis e alertas.
• Views de métricas de modelo: Fontes do modelo, campos, medidas, filtros e junções.
• Gerenciar views de métricas: Controlar o acesso, habilitar a edição colaborativa e gerenciar o ciclo de vida da view de métricas.
• Referência de sintaxe YAML da view de métricas: Consulte a especificação YAML completa da view de métricas.