Partager via

Utiliser des métadonnées sémantiques dans les vues de métriques

Important

Cette fonctionnalité est disponible en préversion publique. Vous pouvez confirmer l’inscription en préversion sur la page Aperçus . Consultez Gérer les préversions d’Azure Databricks.

Cette page explique comment utiliser des métadonnées sémantiques dans les vues de métriques pour améliorer la visualisation des données et améliorer la précision du modèle de langage volumineux (LLM).

Note

Nécessite Databricks Runtime 17.2 ou version ultérieure. Les définitions YAML de la vue métrique doivent utiliser la version 1.1 ou ultérieure de la spécification. Pour plus d’informations, consultez le journal des modifications de spécification de version .

Qu’est-ce que les métadonnées sémantiques ?

Les métadonnées sémantiques incluent des noms d’affichage, des spécifications de format et des synonymes qui fournissent un contexte supplémentaire. Ces métadonnées aident les outils de visualisation, tels que les tableaux de bord IA/BI et les outils en langage naturel, tels que les espaces Génie, interpréter et travailler plus efficacement avec vos données. Les métadonnées sémantiques sont définies dans la définition YAML d’une vue de métrique.

Note

Lorsque vous créez ou modifiez des vues métriques avec la version 1.1 de la spécification, tous les commentaires à ligne unique (indiqués avec #) dans la définition YAML sont supprimés lorsque la définition est enregistrée. Consultez Mettre à niveau votre YAML vers la version 1.1 pour obtenir des options et des recommandations lors de la mise à niveau des définitions YAML existantes.

Noms d’affichage

Les noms d’affichage fournissent des étiquettes visuelles faciles à lire qui apparaissent dans les outils de visualisation au lieu de noms de colonnes techniques. Les noms d’affichage sont limités à 255 caractères.

L'exemple suivant présente les noms d’affichage définis sur la dimension order_date et la mesure 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

Les synonymes aident les outils LLM, tels que AI/BI Genie, à découvrir des dimensions et des mesures par le biais d’entrées utilisateur en fournissant d’autres noms. Vous pouvez définir des synonymes à l’aide d’un style de bloc ou d’un style de flux YAML. Chaque dimension ou mesure peut avoir jusqu’à 10 synonymes. Chaque synonyme est limité à 255 caractères.

L’exemple suivant montre des synonymes définis sur la order_date dimension :

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

Spécifications de format

Les spécifications de format définissent la façon dont les valeurs doivent être affichées dans les outils de visualisation. Les tableaux suivants incluent les types et exemples de format pris en charge.

Formats numériques

Type de format Options requises Options facultatives
Nombre : utilisez le format numérique brut pour les valeurs numériques générales avec des options facultatives de contrôle de place décimale et d’abréviation. type: number
  • decimal_places: contrôle le nombre de places affichées après la décimale.
    • type: (Obligatoire s’il decimal_places est spécifié)
      • max
      • exact
      • all
    • places: valeur entière comprise entre 0 et 10 (obligatoire si le type est max ou exact)
  • hide_group_separator: lorsque la valeur est true, supprime tout séparateur de regroupement de nombres applicable, tel qu’un ,.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Devise : utilisez le format monétaire pour les valeurs monétaires avec des codes monétaires ISO-4217. type: currency
  • currency_code: code ISO-4217 (obligatoire). Par exemple, les codes suivants insèrent le symbole pour les dollars américains, euros et yens, respectivement.
    • USD
    • EUR
    • JPY
  • decimal_places: contrôle le nombre de places affichées après la décimale.
    • type: (Obligatoire s’il decimal_places est spécifié)
      • max
      • exact
      • all
  • hide_group_separator: lorsque la valeur est true, supprime tout séparateur de regroupement de nombres applicable.
    • true
    • false
  • abbreviation:
    • none
    • compact
    • scientific
Pourcentage : utilisez le format de pourcentage pour les valeurs de ratio exprimées en pourcentages. type: percentage
  • decimal_places: contrôle le nombre de places affichées après la décimale.
    • type: (Obligatoire s’il decimal_places est spécifié)
      • max
      • exact
      • all
  • hide_group_separator: lorsque la valeur est true, supprime tout séparateur de regroupement de nombres applicable.
    • true
    • false

Exemples de mise en forme numérique

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

Formats de date et d’heure

Le tableau suivant explique comment utiliser les formats de date et d’heure.

Type de format Options requises Options facultatives
Date : utilisez le format de date pour les valeurs de date avec différentes options d’affichage.
  • type: date
  • date_format: contrôle la façon dont la date est affichée
    • locale_short_month: affiche la date avec un mois abrégé
    • locale_long_month: affiche la date avec le nom complet du mois
    • year_month_day: Met en forme la date en tant que aaaa-MM-DD
    • locale_number_month: affiche la date avec un mois sous forme de nombre
    • year_week: met en forme la date sous la forme d’une année et d’un numéro de semaine. Par exemple, 2025-W1
  • leading_zeros: contrôle si les nombres à chiffres uniques sont précédés d’un zéro
  • true
  • false
DateTime : utilisez le format datetime pour les valeurs d’horodatage combinant date et heure.
  • type: date_time
  • date_format: contrôle la façon dont la date est affichée
    • no_date: La date est masquée
    • locale_short_month: affiche la date avec un mois abrégé
    • locale_long_month: affiche la date avec le nom complet du mois
    • year_month_day: Met en forme la date en tant que aaaa-MM-DD
    • locale_number_month: affiche la date avec un mois sous forme de nombre
    • year_week: met en forme la date sous la forme d’une année et d’un numéro de semaine. Par exemple, 2025-W1
  • time_format:
    • no_time: l'heure est cachée
    • locale_hour_minute: affiche l’heure et la minute
    • locale_hour_minute_second: affiche l’heure, la minute et la seconde
  • leading_zeros: contrôle si les nombres à chiffres uniques sont précédés d’un zéro
    • true
    • false

Note

Lors de l’utilisation d’un type date_time, au moins date_format ou time_format doit spécifier une valeur différente de no_date ou no_time.

Exemples de mise en forme Datetime

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

Exemple complet

L’exemple suivant montre une définition de vue de métrique qui inclut tous les types de métadonnées sémantiques :

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