Pular para o conteúdo principal
Última atualização em

Metadados do agente na visualização de métricas

Os metadados do agente (também conhecidos como metadados semânticos) aprimoram a visualização de dados e melhoram a precisão do modelo de linguagem de grande escala (LLM, na sigla em inglês) ao fornecer nomes de exibição, especificações de formato e sinônimos que contextualizam as métricas para o negócio. Esses metadados ajudam ferramentas de visualização e de processamento de linguagem natural, como o Genie Spaces, a interpretar e trabalhar com seus dados de forma mais eficaz.

nota

Requer o Databricks Runtime 17.3 e o YAML versão 1.1. Consulte os requisitos de versão.

O que são metadados de agente?​

Os metadados do agente incluem nomes de exibição, especificações de formato e sinônimos que fornecem contexto adicional. Esses metadados ajudam ferramentas de visualização, como painéis de AI/BI , e ferramentas de linguagem natural, como Genie Spaces, a interpretar e trabalhar com seus dados de forma mais eficaz. Os metadados do agente são definidos na definição YAML view de métricas.

nota

Ao criar ou alterar uma visualização de métricas com a versão de especificação 1.1, quaisquer comentários de linha única (indicados por #) na definição YAML são removidos quando a definição é salva. Consulte a seção Atualização para YAML 1.1 para obter opções e recomendações ao atualizar definições YAML existentes.

Os exemplos nesta página usam o dataset de amostra TPC-H (samples.tpch.orders), que está disponível por default no conjunto de dadosUnity Catalog. O dataset TPC-H modela uma cadeia de suprimentos atacadista com tabelas para pedidos, clientes, fornecedores e peças. Os nomes das colunas na tabela orders usam o prefixo o_ (por exemplo, o_orderdate para data do pedido, o_totalprice para preço total). Para obter detalhes sobre o esquema e o modelo de dados do TPC-H, consulte o tutorial: Criar uma view de métricas completa com join.

Nomes de exibição​

Os nomes de exibição fornecem rótulos legíveis para humanos que aparecem em ferramentas de visualização em vez dos nomes técnicos das colunas. Os nomes de exibição estão limitados a 255 caracteres.

O exemplo a seguir mostra nomes de exibição definidos na dimensão order_date (acompanhamento quando os pedidos foram feitos) e na medida total_revenue (calculando a soma de todos os preços dos pedidos).

YAML
version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
    display_name: 'Order Date'

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    display_name: 'Total Revenue'

Sinônimos​

Os sinônimos ajudam ferramentas de LLM, como o Genie, a descobrir dimensões e medidas por meio da entrada do usuário, fornecendo nomes alternativos. Você pode definir sinônimos usando YAML no estilo de bloco ou no estilo de fluxo. Cada dimensão ou medida pode ter até 10 sinônimos. Cada sinônimo está limitado a 255 caracteres.

O exemplo a seguir mostra sinônimos definidos na dimensão order_date (quando os pedidos foram feitos) e na medida total_revenue (soma de todos os preços dos pedidos). Os sinônimos permitem que os usuários façam perguntas usando linguagem natural, como "mostre-me a receita por horário do pedido" ou "qual o total de vendas por data do pedido":

YAML
version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
    # block style
    synonyms:
      - 'order time'
      - 'date of order'

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    # flow style
    synonyms: ['revenue', 'total sales']

Especificações de formato​

As especificações de formato definem como os valores devem ser exibidos nas ferramentas de visualização. As tabelas a seguir incluem os tipos de formato suportados e exemplos.

Formatos numéricos​

Tipo de formato

Opções obrigatórias

Opções opcionais

Número : Use o formato de número simples para valores numéricos em geral, com controle opcional de casas decimais e opções de abreviação.

type: number

  • decimal_places: Controla o número de casas decimais exibidas.

    • type: (Obrigatório se decimal_places for especificado)

      • max
      • exact
      • all

    • places: Valor inteiro de 0 a 10 (obrigatório se o tipo for max ou exact)

  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento de números aplicável, como ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Moeda : Utilize o formato de moeda para valores monetários com códigos de moeda ISO-4217.

type: currency

  • currency_codeCódigo ISO-4217 (obrigatório). Por exemplo, os seguintes códigos inserem o símbolo para dólares americanos, euros e ienes, respectivamente.

    • USD
    • EUR
    • JPY

  • decimal_places: Controla o número de casas decimais exibidas.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all

  • hide_group_separatorQuando definido como verdadeiro, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Porcentagem : Utilize o formato de porcentagem para valores de razão expressos em porcentagem.

type: percentage

  • decimal_places: Controla o número de casas decimais exibidas.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all

  • hide_group_separatorQuando definido como verdadeiro, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

Byte : Use o formato de byte para exibir os valores de tamanho de dados com as unidades de byte apropriadas (KB, MB, GB, etc.).

type: byte

  • decimal_places: Controla o número de casas decimais exibidas.

    • type: (Obrigatório se decimal_places for especificado)

      • max
      • exact
      • all

    • places: Valor inteiro de 0 a 10 (obrigatório se o tipo for max ou exact)

  • hide_group_separatorQuando definido como verdadeiro, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

Exemplos de formatação numérica​

YAML
format:
  type: number
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false
  abbreviation: compact

Formatos de data e hora​

A tabela a seguir explica como trabalhar com formatos de data e hora.

Tipo de formato

Opções obrigatórias

Opções opcionais

Data : Utilize o formato de data para valores de data com diversas opções de exibição.

  • type: date
  • date_formatControla a forma como a data é exibida.
    • locale_short_monthExibe a data com o mês abreviado.
    • locale_long_monthExibe a data com o nome completo do mês.
    • year_month_dayFormata a data como AAAA-MM-DD
    • locale_number_monthExibe a data com o mês representado por um número.
    • year_weekFormata a data como um ano e um número de semana. Por exemplo, 2025-W1
  • leading_zeros: Controla se os números de um único dígito são precedidos por um zero
  • true
  • false

Data e hora : Use o formato de data e hora para valores de carimbo de data/hora que combinam data e hora.

  • type: date_time

  • date_formatControla a forma como a data é exibida.

    • no_dateA data está oculta.
    • locale_short_monthExibe a data com o mês abreviado.
    • locale_long_monthExibe a data com o nome completo do mês.
    • year_month_dayFormata a data como AAAA-MM-DD
    • locale_number_monthExibe a data com o mês representado por um número.
    • year_weekFormata a data como um ano e um número de semana. Por exemplo, 2025-W1

  • time_format:

    • no_timeO tempo está oculto
    • locale_hour_minuteExibe a hora e os minutos.
    • locale_hour_minute_secondExibe a hora, os minutos e os segundos.
  • leading_zeros: Controla se os números de um único dígito são precedidos por um zero
    • true
    • false
nota

Ao trabalhar com um tipo date_time , pelo menos um de date_format ou time_format deve especificar um valor diferente de no_date ou no_time.

Exemplos de formatação de data e hora​

YAML
format:
  type: date
  date_format: year_month_day
  leading_zeros: true

Integração de ferramentas downstream​

Os metadados semânticos preenchem automaticamente as ferramentas subsequentes que consomem a view de métricas:

  • Painéis deAI/BI : Os nomes de exibição e as especificações de formato são preenchidos automaticamente no conjunto de dados e nas visualizações do painel para melhorar a legibilidade.
  • EspaçosGenie : Os sinônimos são importados automaticamente para ajudar Genie a descobrir e compreender melhor as dimensões e medidas disponíveis na view de métricas.

Exemplo completo​

O exemplo a seguir mostra uma definição view de métricas que rastreia o desempenho das vendas e inclui todos os tipos de metadados do agente. A view de métricas analisa os dados de pedidos para calcular métricas de receita, segmentar clientes por valor do pedido e acompanhar os volumes de pedidos.

Os segmentos de clientes são definidos da seguinte forma:

  • Empresas: Pedidos acima de US$ 100.000
  • Mercado intermediário: Pedidos entre US$ 10.000 e US$ 100.000
  • Pequenas e médias empresas: Pedidos abaixo de US$ 10.000

Os metadados suportam consultas em linguagem natural, como "mostrar o total de vendas por segmento de clientes" ou "qual é a receita média por pedido".

YAML
version: 1.1
source: samples.tpch.orders
comment: Comprehensive sales metrics with enhanced semantic metadata
dimensions:
  - name: order_date
    expr: o_orderdate
    comment: Date when the order was placed
    display_name: Order Date
    format:
      type: date
      date_format: year_month_day
      leading_zeros: true
    synonyms:
      - order time
      - date of order
  - name: customer_segment
    expr: |
      CASE
        WHEN o_totalprice > 100000 THEN 'Enterprise'
        WHEN o_totalprice > 10000 THEN 'Mid-market'
        ELSE 'SMB'
      END
    comment: Customer classification based on order value
    display_name: Customer Segment
    synonyms:
      - segment
      - customer tier
measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: Total revenue from all orders
    display_name: Total Revenue
    format:
      type: currency
      currency_code: USD
      decimal_places:
        type: exact
        places: 2
      hide_group_separator: false
      abbreviation: compact
    synonyms:
      - revenue
      - total sales
      - sales amount
  - name: order_count
    expr: COUNT(1)
    comment: Total number of orders
    display_name: Order Count
    format:
      type: number
      decimal_places:
        type: all
      hide_group_separator: true
    synonyms:
      - count
      - number of orders
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(1)
    comment: Average revenue per order
    display_name: Average Order Value
    format:
      type: currency
      currency_code: USD
      decimal_places:
        type: exact
        places: 2
    synonyms:
      - aov
      - average revenue
Nesta página