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

Metadados do agente em views de métricas

Metadados de agente (também conhecidos como metadados semânticos) aprimoram a visualização de dados e melhoram a precisão do modelo de linguagem grande (LLM), fornecendo nomes de exibição, especificações de formato e sinônimos que dão contexto de negócios às suas métricas. Estes metadados ajudam ferramentas de visualização e ferramentas de linguagem natural como Genie Agents a interpretar e trabalhar com seus dados de forma mais eficaz.

nota

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

O que são metadados do 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 dashboards de AI/BI, e ferramentas de linguagem natural, como os Agentes Genie, a interpretar e trabalhar com seus dados de forma mais eficaz. Os metadados do agente são definidos na definição YAML da view de métricas.

nota

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

Os exemplos desta página usam o dataset de amostra TPC-H (samples.tpch.orders), que está disponível por default em datasets do Unity Catalog. O dataset TPC-H modela uma cadeia de suprimentos de atacado com tabelas para pedidos, clientes, fornecedores e peças. Nomes de coluna 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 TPC-H e o modelo de dados, consulte Tutorial: criar uma view de métricas com join e modelagem de dados.

Nomes de exibição​

Nomes de exibição fornecem rótulos legíveis por humanos que aparecem em ferramentas de visualização em vez de nomes de colunas técnicas. Nomes de exibição são limitados a 255 caracteres.

O exemplo a seguir mostra nomes de exibição definidos no campo order_date (acompanhamento de quando os pedidos foram feitos) e na medida total_revenue (cálculo da soma de todos os preços dos pedidos).

YAML
version: 1.1
source: samples.tpch.orders

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

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

Sinônimos​

Sinônimos ajudam as ferramentas LLM, como o Genie, a descobrir campos (também chamados de dimensões) e medidas por meio da entrada do usuário, fornecendo nomes alternativos. Você pode definir sinônimos usando YAML de estilo de bloco ou de estilo de fluxo. Cada campo ou medida pode ter até 10 sinônimos. Cada sinônimo é limitado a 255 caracteres.

O exemplo a seguir mostra sinônimos definidos no campo 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 tempo de pedido" ou "quais são as vendas totais por data de pedido":

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - 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​

Especificações de formato definem como os valores devem ser exibidos em ferramentas de visualização. As tabelas a seguir incluem tipos de formato compatíveis 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 gerais 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 true (verdadeiro), remove qualquer separador de agrupamento de números aplicável, como um ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

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

type: currency

  • currency_code: código ISO-4217 (obrigatório). Por exemplo, os códigos a seguir 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_separator: Quando definido como true, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Porcentagem : Use o formato de porcentagem para valores de proporção expressos como porcentagens.

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_separator: Quando definido como true, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

Byte : Use o formato byte para valores de tamanho de dados exibidos com 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_separator: Quando definido como true, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

Tipo de Formato

Opções obrigatórias

Opções Opcionais

Número : use o formato de número simples para valores numéricos gerais 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 true (verdadeiro), remove qualquer separador de agrupamento de números aplicável, como um ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

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

type: currency

  • currency_code: código ISO-4217 (obrigatório). Por exemplo, os códigos a seguir 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_separator: Quando definido como true, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Porcentagem : Use o formato de porcentagem para valores de proporção expressos como porcentagens.

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_separator: Quando definido como true, remove qualquer separador de agrupamento de números aplicável.

    • true
    • false

Byte : Use o formato byte para valores de tamanho de dados exibidos com 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_separator: Quando definido como true, 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 : use o formato de data para valores de data com várias opções de exibição.

  • type: date
  • date_formatControla como a data é exibida
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com o mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1
  • leading_zeros: Controla se números de um dígito são precedidos por um zero.
  • true
  • false

Data/hora : Use o formato de data/hora para valores de timestamp combinando data e hora.

  • type: date_time

  • date_formatControla como a data é exibida

    • no_date: A data está oculta
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com o mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1

  • time_format:

    • no_time: A hora está oculta
    • locale_hour_minuteExibe a hora e o minuto
    • locale_hour_minute_second: Exibe a hora, o minuto e o segundo
  • leading_zeros: Controla se números de um dígito são precedidos por um zero.
    • true
    • false

Tipo de Formato

Opções obrigatórias

Opções Opcionais

Data : use o formato de data para valores de data com várias opções de exibição.

  • type: date
  • date_formatControla como a data é exibida
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com o mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1
  • leading_zeros: Controla se números de um dígito são precedidos por um zero.
  • true
  • false

Data/hora : Use o formato de data/hora para valores de timestamp combinando data e hora.

  • type: date_time

  • date_formatControla como a data é exibida

    • no_date: A data está oculta
    • locale_short_month: Exibe a data com um mês abreviado
    • locale_long_month: Exibe a data com o nome completo do mês
    • year_month_day: Formata a data como AAAA-MM-DD
    • locale_number_month: Exibe a data com o mês como um número
    • year_week: Formata a data como um ano e um número de semana. Por exemplo, 2025-W1

  • time_format:

    • no_time: A hora está oculta
    • locale_hour_minuteExibe a hora e o minuto
    • locale_hour_minute_second: Exibe a hora, o minuto e o segundo
  • leading_zeros: Controla se números de um 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​

Metadados semânticos preenchem automaticamente as ferramentas downstream que consomem a view de métricas:

  • Dashboards de AI/BI : Os nomes de exibição e as especificações de formato são preenchidos automaticamente nos datasets e visualizações do dashboard para melhorar a legibilidade do dashboard.
  • Agentes Genie : Sinônimos são importados automaticamente para ajudar o Genie a descobrir e entender melhor os campos e as medidas disponíveis na visualização de métricas.

Exemplo completo​

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

Segmentos de clientes são definidos da seguinte forma:

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

Os metadados suportam queries de linguagem natural, como "mostre-me o total de ventas por segmento de cliente" ou "qual é a receita média por pedido.".

YAML
version: 1.1
source: samples.tpch.orders
comment: Comprehensive sales metrics with enhanced semantic metadata
fields:
  - 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