Pular para o conteúdo principal

Usar metadados semânticos na visualização de métricas

info

Visualização

Este recurso está em Visualização Pública.

Esta página explica como usar metadados semânticos na visualização de métricas para aprimorar a visualização de dados e melhorar a precisão do modelo de linguagem grande (LLM).

nota

Requer Databricks Runtime 17.2 ou acima. As definições YAML view de métricas devem usar a versão de especificação 1.1 ou acima. Veja o changelog da especificação da versão para mais detalhes.

O que são metadados semânticos?

Metadados semânticos 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. Metadados semânticos são definidos na definição YAML de uma view de métricas.

nota

Quando você cria ou altera a exibição de métricas com a versão de especificação 1.1, todos os comentários de linha única (indicados com #) na definição YAML são removidos quando a definição é salva. Consulte Atualize seu YAML para 1.1 para obter opções e recomendações ao atualizar definições de YAML existentes.

Os seguintes tipos de metadados podem ser incluídos:

Nomes de exibição

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

O exemplo a seguir mostra nomes de exibição definidos na dimensão order_date e na medida total_revenue .

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

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

O exemplo a seguir mostra sinônimos definidos na dimensão order_date :

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 tipos de formatos suportados e exemplos.

Formatos Numéricos

Tipo de formato

Opções necessárias

Opções opcionais

Número : use o formato numérico simples para valores numéricos gerais com controle de casas decimais opcionais e opções de abreviação.

type: number

  • decimal_places: Controla o número de casas decimais mostradas após o decimal.

    • 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 numérico aplicável, como ,.

    • 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 mostradas após o decimal.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all
  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento numérico 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 mostradas após o decimal.

    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all
  • hide_group_separator: Quando definido como verdadeiro, remove qualquer separador de agrupamento numérico 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 necessá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_format: Controla a maneira 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 um 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 único dígito são precedidos por zero
  • true
  • false

DateTime : Use o formato datetime para valores de registro de data e hora combinando data e hora.

  • type: date_time

  • date_format: Controla a maneira como a data é exibida

    • no_date:Data 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 um 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:O tempo está escondido
    • locale_hour_minute: Exibe 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 único dígito são precedidos por 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

Exemplo completo

O exemplo a seguir mostra uma definição view de métricas que inclui todos os tipos de metadados semânticos:

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