Aller au contenu principal
Dernière mise à jour le

Métadonnées d'agent dans les vues métriques

Les métadonnées d'agent (également appelées métadonnées sémantiques) améliorent la visualisation des données et la précision des grands modèles linguistiques (LLM) en fournissant des noms d'affichage, des spécifications de format et des synonymes qui donnent un contexte commercial à vos métriques. Ces métadonnées aident les outils de visualisation et les outils de langage naturel, tels que les agents Genie, à interpréter et à travailler plus efficacement avec vos données.

remarque

Nécessite Databricks Runtime 17.3 et YAML version 1.1. Consultez les exigences de version.

Qu'est-ce que les métadonnées d'agent ?​

Les métadonnées de l'agent comprennent les noms d'affichage, les spécifications de format et les synonymes qui fournissent un contexte supplémentaire. Ces métadonnées aident les outils de visualisation, tels que les tableaux de bord AI/BI, et les outils de langage naturel, tels que les Agents Genie, à interpréter et à travailler plus efficacement avec vos données. Les métadonnées d'agent sont définies dans la définition YAML de la vue des métriques.

remarque

Lorsque vous créez ou modifiez des vues de métriques avec la version 1.1 de la spécification, tous les commentaires monolignes (indiqués par #) dans la définition YAML sont supprimés lors de l'enregistrement de la définition. Consultez Mettre à niveau vers YAML 1.1 pour les options et les recommandations lors de la mise à niveau des définitions YAML existantes.

Les exemples sur cette page utilisent l'exemple de dataset TPC-H (samples.tpch.orders), qui est disponible par default dans Unity Catalog datasets. Le dataset TPC-H modélise une chaîne d'approvisionnement en gros avec des tables pour les commandes, les clients, les fournisseurs et les pièces. Les noms de colonnes de la table orders utilisent le préfixe o_ (par exemple, o_orderdate pour la date de commande, o_totalprice pour le prix total). Pour plus de détails sur le schéma TPC-H et le modèle de données, consultez Tutoriel : créer une vue métrique avec des jointures et la modélisation des données.

Noms d'affichage​

Les noms d'affichage fournissent des étiquettes lisibles par l'utilisateur qui apparaissent dans les outils de visualisation au lieu des noms de colonnes techniques. Les noms d'affichage sont limités à 255 caractères.

L'exemple suivant montre les noms d'affichage définis sur le champ order_date (suivi du moment où les commandes ont été passées) et la mesure total_revenue (calculant la somme de tous les prix de commande).

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - name: order_date
    expr: o_orderdate
    display_name: 'Order Date'

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
    display_name: 'Total Revenue'

Synonymes​

Les synonymes aident les outils LLM, tels que Genie, à découvrir des champs (également appelés dimensions) et des mesures grâce aux entrées utilisateur en fournissant des noms alternatifs. Vous pouvez définir des synonymes en utilisant le style bloc ou le style flux YAML. Chaque champ ou mesure peut avoir jusqu'à 10 synonymes. Chaque synonyme est limité à 255 caractères.

L'exemple suivant montre les synonymes définis sur le champ order_date (lorsque les commandes ont été passées) et la mesure total_revenue (somme de tous les prix de commande). Les synonymes permettent aux utilisateurs de poser des questions en langage naturel telles que « affiche-moi les revenus par heure de commande » ou « quels sont les ventes totales par date de commande » :

YAML
version: 1.1
source: samples.tpch.orders

fields:
  - 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 manière dont les valeurs doivent être affichées dans les outils de visualisation. Les tableaux suivants incluent les types de format pris en charge et des exemples.

Formats numériques​

Type de format

Options requises

Options facultatives

Nombre : Utilisez le format numérique simple pour les valeurs numériques générales avec un contrôle optionnel des décimales et des options d'abréviation.

type: number

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)

      • max
      • exact
      • all

    • places: Valeur entière de 0 à 10 (requis si le type est max ou exact)

  • hide_group_separator: lorsqu'il est défini sur true, supprime tout séparateur de regroupement de nombres applicable, tel que ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Devise : Utilisez le format de devise pour les valeurs monétaires avec les codes de devise ISO-4217.

type: currency

  • currency_code: code ISO-4217 (obligatoire). Par exemple, les codes suivants insèrent le symbole du dollar américain, de l'euro et du yen, respectivement.

    • USD
    • EUR
    • JPY

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)
      • max
      • exact
      • all

  • hide_group_separator: Lorsque l'option est définie sur 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 décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)
      • max
      • exact
      • all

  • hide_group_separator: Lorsque l'option est définie sur true, supprime tout séparateur de regroupement de nombres applicable.

    • true
    • false

Octet : utilisez le format d'octet pour les valeurs de taille de données affichées avec les unités d'octet appropriées (Ko, Mo, Go, etc.).

type: byte

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)

      • max
      • exact
      • all

    • places: Valeur entière de 0 à 10 (requis si le type est max ou exact)

  • hide_group_separator: Lorsque l'option est définie sur true, supprime tout séparateur de regroupement de nombres applicable.

    • true
    • false

Type de format

Options requises

Options facultatives

Nombre : Utilisez le format numérique simple pour les valeurs numériques générales avec un contrôle optionnel des décimales et des options d'abréviation.

type: number

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)

      • max
      • exact
      • all

    • places: Valeur entière de 0 à 10 (requis si le type est max ou exact)

  • hide_group_separator: lorsqu'il est défini sur true, supprime tout séparateur de regroupement de nombres applicable, tel que ,.

    • true
    • false

  • abbreviation:

    • none
    • compact
    • scientific

Devise : Utilisez le format de devise pour les valeurs monétaires avec les codes de devise ISO-4217.

type: currency

  • currency_code: code ISO-4217 (obligatoire). Par exemple, les codes suivants insèrent le symbole du dollar américain, de l'euro et du yen, respectivement.

    • USD
    • EUR
    • JPY

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)
      • max
      • exact
      • all

  • hide_group_separator: Lorsque l'option est définie sur 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 décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)
      • max
      • exact
      • all

  • hide_group_separator: Lorsque l'option est définie sur true, supprime tout séparateur de regroupement de nombres applicable.

    • true
    • false

Octet : utilisez le format d'octet pour les valeurs de taille de données affichées avec les unités d'octet appropriées (Ko, Mo, Go, etc.).

type: byte

  • decimal_places: Contrôle le nombre de décimales affichées après la virgule.

    • type: (obligatoire si decimal_places est spécifié)

      • max
      • exact
      • all

    • places: Valeur entière de 0 à 10 (requis si le type est max ou exact)

  • hide_group_separator: Lorsque l'option est définie sur true, supprime tout séparateur de regroupement de nombres applicable.

    • true
    • false

Exemples de formatage numérique​

YAML
format:
  type: number
  decimal_places:
    type: max
    places: 2
  hide_group_separator: false
  abbreviation: compact

Formats de date et d'heure​

Le tableau suivant explique comment travailler avec 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: formate la date au format AAAA-MM-JJ
    • locale_number_month: Affiche la date avec un mois sous forme de nombre.
    • year_week: formate la date sous forme d'année et de numéro de semaine. Par exemple, 2025-W1
  • leading_zeros: Contrôle si les nombres à un chiffre sont précédés d'un zéro
  • true
  • false

DateTime : Utilisez le format datetime pour les valeurs de Timestamp combinant la date et l'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: formate la date au format AAAA-MM-JJ
    • locale_number_month: Affiche la date avec un mois sous forme de nombre.
    • year_week: formate la date sous forme d'année et de numéro de semaine. Par exemple, 2025-W1

  • time_format:

    • no_time: Le temps est masqué
    • 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 à un chiffre sont précédés d'un zéro
    • true
    • false

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: formate la date au format AAAA-MM-JJ
    • locale_number_month: Affiche la date avec un mois sous forme de nombre.
    • year_week: formate la date sous forme d'année et de numéro de semaine. Par exemple, 2025-W1
  • leading_zeros: Contrôle si les nombres à un chiffre sont précédés d'un zéro
  • true
  • false

DateTime : Utilisez le format datetime pour les valeurs de Timestamp combinant la date et l'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: formate la date au format AAAA-MM-JJ
    • locale_number_month: Affiche la date avec un mois sous forme de nombre.
    • year_week: formate la date sous forme d'année et de numéro de semaine. Par exemple, 2025-W1

  • time_format:

    • no_time: Le temps est masqué
    • 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 à un chiffre sont précédés d'un zéro
    • true
    • false
remarque

Lorsque vous travaillez avec un type date_time, au moins l'un de date_format ou time_format doit spécifier une valeur autre que no_date ou no_time.

Exemples de formatage de date-heure​

YAML
format:
  type: date
  date_format: year_month_day
  leading_zeros: true

Intégration d’outils en aval​

Les métadonnées sémantiques remplissent automatiquement les outils en aval qui consomment la vue de métriques :

  • tableaux de bord AI/BI : les noms d'affichage et les spécifications de format sont automatiquement renseignés dans les datasets et les visualisations des tableaux de bord pour améliorer la lisibilité des tableaux de bord.
  • Agents Genie : Les synonymes sont automatiquement importés pour aider Genie à mieux découvrir et comprendre les champs et les mesures disponibles à partir de la vue métrique.

Exemple complet​

L'exemple suivant présente une définition d'affichage métrique qui suit les performances de Ventes et inclut tous les types de métadonnées d'agent. L'affichage métrique analyse les données de commande pour calculer les métriques de revenus, segmenter les clients par valeur de commande et suivre les volumes de commande.

Les segments de clients sont définis comme suit :

  • Entreprise : Commandes de plus de 100 000 $
  • Marché intermédiaire : Commandes entre 10 000 $ et 100 000 $
  • Petites et moyennes entreprises : Commandes inférieures à 10 000 $

Les métadonnées prennent en charge les requêtes en langage naturel telles que « montrez-moi les ventes totales par segment de clientèle » ou « quel est le revenu moyen par commande ».

YAML
version: 1.1
source: samples.tpch.orders
comment: Comprehensive sales metrics with enhanced semantic metadata
fields:
  - 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
Sur cette page