Compartir a través de

Uso de metadatos semánticos en vistas de métricas

Importante

Esta característica está en versión preliminar pública.

En esta página se explica cómo usar metadatos semánticos en vistas de métricas para mejorar la visualización de datos y mejorar la precisión del modelo de lenguaje grande (LLM).

Nota:

Requiere Databricks Runtime 17.2 o superior. Las definiciones de YAML de la vista de métricas deben usar la versión 1.1 o posterior de la especificación. Consulte Registro de cambios de especificación de versión para obtener más información.

¿Qué son los metadatos semánticos?

Los metadatos semánticos incluyen nombres para mostrar, especificaciones de formato y sinónimos que proporcionan contexto adicional. Estos metadatos ayudan a las herramientas de visualización, como los paneles de IA/BI y las herramientas de lenguaje natural, como espacios de Genie, interpretar y trabajar con los datos de forma más eficaz. Los metadatos semánticos se definen en la definición de YAML de una vista de métrica.

Nota:

Al crear o modificar vistas de métricas con la versión 1.1 de la especificación, se quitan los comentarios de una sola línea (indicados con #) en la definición de YAML cuando se guarda la definición. Consulte Actualización de YAML a 1.1 para obtener opciones y recomendaciones al actualizar las definiciones de YAML existentes.

Nombres para mostrar

Los nombres para mostrar proporcionan etiquetas legibles que aparecen en herramientas de visualización en lugar de nombres de columna técnicos. Los nombres para mostrar están limitados a 255 caracteres.

En el ejemplo siguiente se muestran nombres para mostrar definidos en la dimensión order_date y la 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

Los sinónimos ayudan a las herramientas de LLM, como AI/BI Genie, a detectar dimensiones y medidas a través de la entrada del usuario proporcionando nombres alternativos. Puede definir sinónimos mediante el estilo de bloque o el estilo de flujo YAML. Cada dimensión o medida puede tener hasta 10 sinónimos. Cada sinónimo está limitado a 255 caracteres.

En el ejemplo siguiente se muestran sinónimos definidos en la order_date dimensión:

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

Especificaciones de formato

Las especificaciones de formato definen cómo se deben mostrar los valores en las herramientas de visualización. Las tablas siguientes incluyen ejemplos y tipos de formato admitidos.

Formatos numéricos

Tipo de formato Opciones necesarias Opciones opcionales
Número: use el formato de número simple para los valores numéricos generales con posibilidad opcional de control de posición decimal y opciones de abreviatura. type: number
  • decimal_places: controla el número de lugares que se muestran después del decimal.
    • type: (Obligatorio si decimal_places se especifica)
      • max
      • exact
      • all
    • places: valor entero comprendido entre 0 y 10 (obligatorio si el tipo es max o exact)
  • hide_group_separator: cuando se establece en true, quita cualquier separador de agrupación de números aplicable, como .,
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Moneda: use el formato de moneda para los valores monetarios con códigos de moneda ISO-4217. type: currency
  • currency_code: código ISO-4217 (obligatorio). Por ejemplo, los códigos siguientes insertan el símbolo para dólares estadounidenses, Euros e Yen, respectivamente.
    • USD
    • EUR
    • JPY
  • decimal_places: controla el número de lugares que se muestran después del decimal.
    • type: (Obligatorio si decimal_places se especifica)
      • max
      • exact
      • all
  • hide_group_separator: cuando se establece en true, quita cualquier separador de agrupación de números aplicable.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Porcentaje: use el formato de porcentaje para los valores de proporción expresados como porcentajes. type: percentage
  • decimal_places: controla el número de lugares que se muestran después del decimal.
    • type: (Obligatorio si decimal_places se especifica)
      • max
      • exact
      • all
  • hide_group_separator: cuando se establece en true, quita cualquier separador de agrupación de números aplicable.
    • true
    • false

Ejemplos de formato numérico

Number
format:
  type: number
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false
  abbreviation: compact
Moneda
format:
  type: currency
  currency_code: USD
  decimal_places:
    type: exact
    places: 2
  hide_group_separator: false
  abbreviation: compact
Porcentaje
format:
  type: percentage
  decimal_places:
    type: all
  hide_group_separator: true

Formatos de fecha y hora

En la tabla siguiente se explica cómo trabajar con formatos de fecha y hora.

Tipo de formato Opciones necesarias Opciones opcionales
Fecha: use el formato de fecha para los valores de fecha con varias opciones de presentación.
  • type: date
  • date_format: controla la forma en que se muestra la fecha.
    • locale_short_month: muestra la fecha con un mes abreviado.
    • locale_long_month: muestra la fecha con el nombre completo del mes.
    • year_month_day: da formato a la fecha como AAAA-MM-DD
    • locale_number_month: muestra la fecha con un mes como un número.
    • year_week: da formato a la fecha como un año y un número de semana. Por ejemplo: 2025-W1
  • leading_zeros: controla si los números de un solo dígito van precedidos de un cero.
  • true
  • false
DateTime: use el formato datetime para los valores de marca de tiempo que combinan fecha y hora.
  • type: date_time
  • date_format: controla la forma en que se muestra la fecha.
    • no_date: la fecha está oculta
    • locale_short_month: muestra la fecha con un mes abreviado.
    • locale_long_month: muestra la fecha con el nombre completo del mes.
    • year_month_day: da formato a la fecha como AAAA-MM-DD
    • locale_number_month: muestra la fecha con un mes como un número.
    • year_week: da formato a la fecha como un año y un número de semana. Por ejemplo: 2025-W1
  • time_format:
    • no_time: El tiempo está oculto.
    • locale_hour_minute: muestra la hora y el minuto.
    • locale_hour_minute_second: muestra la hora, el minuto y el segundo.
  • leading_zeros: controla si los números de un solo dígito van precedidos de un cero.
    • true
    • false

Nota:

Cuando se trabaja con un tipo de date_time, al menos uno de date_format o time_format debe especificar un valor distinto de no_date o no_time.

Ejemplos de formato de fecha y hora

Fecha
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

Ejemplo completo

En el ejemplo siguiente se muestra una definición de vista de métrica que incluye todos los tipos de metadatos 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