Compartilhar via

Usar metadados semânticos em exibições de métrica

Importante

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

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

Observação

Requer o Databricks Runtime 17.2 ou superior. As definições yaml de exibição de métrica devem usar a versão de especificação 1.1 ou superior. Consulte o registro de alterações das especificações de versão para obter 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 as ferramentas de visualização, como painéis de IA/BI, e ferramentas de linguagem natural, como espaços do Genie, a interpretar e trabalhar com seus dados com mais eficiência. Metadados semânticos são definidos na definição YAML de uma exibição de métrica.

Observação

Quando você cria ou altera exibições de métrica com a especificação versã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 Atualizar seu YAML para 1.1 para obter opções e recomendações ao atualizar definições yaml existentes.

Nomes de exibição

Os 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. Os nomes de exibição são limitados a 255 caracteres.

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

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'

Synonyms

Os sinônimos ajudam as ferramentas LLM, como o Genie de IA/BI, 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 order_date dimensão:

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 exemplos e tipos de formato compatíveis.

Formatos numéricos

Tipo de formato Opções necessárias Opções opcionais
Número: use o formato de número simples para valores numéricos gerais com opções de controle de casas decimais e de abreviação. type: number
  • decimal_places: controla o número de locais mostrados após a 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 true, 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 locais mostrados após a decimal.
    • 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
Percentual: use o formato de porcentagem para valores de taxa expressos como porcentagens. type: percentage
  • decimal_places: controla o número de locais mostrados após a decimal.
    • 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

Exemplos de formatação numérica

Número
format:
  type: number
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false
  abbreviation: compact
Moeda
format:
  type: currency
  currency_code: USD
  decimal_places:
    type: exact
    places: 2
  hide_group_separator: false
  abbreviation: compact
Porcentagem
format:
  type: percentage
  decimal_places:
    type: all
  hide_group_separator: true

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 YYYY-MM-DD
    • locale_number_month: exibe a data com um mês como um número
    • year_week: formata a data como um número de ano e uma semana. Por exemplo, 2025-W1
  • leading_zeros: controla se os números de dígito único são precedidos por zero
  • true
  • false
DateTime: Use o formato datetime para valores de timestamp que combinam data e hora.
  • type: date_time
  • date_format: controla a maneira 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 YYYY-MM-DD
    • locale_number_month: exibe a data com um mês como um número
    • year_week: formata a data como um número de ano e uma semana. Por exemplo, 2025-W1
  • time_format:
    • no_time: o tempo está oculto
    • 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 os números de dígito único são precedidos por zero
    • true
    • false

Observação

Ao trabalhar com um date_time tipo, 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 datetime

Date
format:
  type: date
  date_format: year_month_day
  leading_zeros: true
DateTime
format:
  type: date_time
  date_format: year_month_day
  time_format: locale_hour_minute_second
  leading_zeros: false

Exemplo completo

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

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
  • Last updated on