Partilhar via

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

Importante

Este recurso está no Public Preview.

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

Observação

Requer Databricks Runtime 17.2 ou superior. As definições de YAML de visualização métrica devem usar a especificação versão 1.1 ou superior. Consulte histórico de alterações da especificação de versão para obter detalhes.

O que são metadados semânticos?

Os metadados semânticos incluem nomes para 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 Genie, a interpretar e trabalhar com seus dados de forma mais eficaz. Os metadados semânticos são definidos na definição YAML de uma visualização métrica.

Observação

Quando você cria ou altera exibições de métricas 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 as definições de YAML existentes.

Nomes para 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 nomes de exibição definidos na order_date dimensão e na total_revenue medida.

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 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 está limitado a 255 caracteres.

O exemplo seguinte mostra sinónimos definidos na 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 tipos de formato suportados e exemplos.

Formatos numéricos

Tipo de formato Opções Necessárias Opções opcionais
Número: Utilize o formato de número simples para valores gerais numéricos, com opções de controlo opcional de casas decimais e abreviação. type: number
  • decimal_places: Controla o número de lugares mostrados após a casa decimal.
    • type: (Obrigatório se decimal_places for especificado)
      • max
      • exact
      • all
    • places: Valor inteiro de 0-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 lugares mostrados após a casa 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
Porcentagem: Use o formato de porcentagem para valores de proporção expressos em porcentagens. type: percentage
  • decimal_places: Controla o número de lugares mostrados após a casa 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
Percentagem
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 forma como a data é apresentada
    • 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 dígito são precedidos por um zero
  • true
  • false
DateTime: Utilize o formato DateTime para carimbos de data e hora, combinando data e hora.
  • type: date_time
  • date_format: Controla a forma como a data é apresentada
    • 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 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 dígito são precedidos por um 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 data/hora

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 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