Partager via

Informations de référence sur la syntaxe YAML

Les définitions d’affichage des métriques suivent la syntaxe de notation YAML standard. Cette page explique comment définir une vue de métrique.

Consultez la documentation de la spécification YAML 1.2.2 pour en savoir plus sur les spécifications YAML.

Vue d’ensemble de YAML

La définition YAML pour une vue de métrique comprend les champs de niveau supérieur suivants :

  • version : La valeur par défaut est 1.1. Il s’agit de la version de la spécification de la vue métrique. Consultez le journal des modifications de spécification de version.
  • source: Les données sources pour la vue métrique. Il peut s’agir d’une ressource de type table ou d’une requête SQL.
  • joins: facultatif. Les jointures de schéma en étoile et de schéma flocon sont prises en charge.
  • filter: facultatif. Expression booléenne SQL qui s’applique à toutes les requêtes ; équivalent à la WHERE clause.
  • comment: facultatif. Description de l’affichage des métriques.
  • dimensions: tableau de définitions de dimension, y compris le nom et l’expression de la dimension.
  • measures: un ensemble de colonnes d'expressions d'agrégation.

Références de nom de colonne

Lorsque vous référencez des noms de colonnes qui contiennent des espaces ou des caractères spéciaux dans des expressions YAML, placez le nom de colonne entre guillemets inversés pour échapper à l’espace ou au caractère. Si l’expression commence par un accent grave et sert directement de valeur YAML, mettez l’expression entière entre guillemets doubles. Les valeurs YAML valides ne peuvent pas commencer par un accent grave.

Exemples de mise en forme

Utilisez les exemples suivants pour apprendre à mettre en forme YAML correctement dans les scénarios courants.

Référencer un nom de colonne

Le tableau suivant montre comment mettre en forme les noms de colonnes en fonction des caractères qu’ils contiennent.

Cas Nom(s) de colonne source Expression(s) de référence Remarques
Aucun espace revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 Utilisez des guillemets doubles, des guillemets simples ou pas de guillemets autour du nom de la colonne.
Avec des espaces First Name expr: "`First Name`" Utilisez des accents graves comme caractères d’échappement des espaces. Placez l’expression entière entre guillemets doubles.
Nom de colonne avec des espaces dans une expression SQL First Name et Last Name expr: CONCAT(`First Name`, , `Last Name`) Si l’expression ne commence pas par des accents graves, les guillemets doubles ne sont pas nécessaires.
Les guillemets sont inclus dans le nom de la colonne source "name" expr: '`"name"`' Utilisez des accents graves comme caractères d’échappement des guillemets doubles dans le nom de la colonne. Placez cette expression entre guillemets simples dans la définition YAML.

Utiliser des expressions avec des deux-points

Cas Expression Remarques
Expressions avec deux-points expr: "CASE WHEN Niveau client = 'Enterprise: Premium' THEN 1 ELSE 0 END" Encapsuler l’expression entière entre guillemets doubles pour une interprétation correcte

Note

YAML interprète les deux-points sans guillemets comme des séparateurs clé-valeur. Utilisez toujours des guillemets doubles autour des expressions qui incluent des points-virgules.

Indentation sur plusieurs lignes

Cas Expression Remarques
Indentation sur plusieurs lignes expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Indenter l'expression sous la première ligne

Note

Utilisez le | scalaire de bloc après expr: pour les expressions multilignes. Toutes les lignes doivent être indentées d'au moins deux espaces au-delà de la clé expr pour une analyse correcte.

Définir une dimension

L’exemple suivant montre comment définir des dimensions :

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Définir une mesure

L’exemple suivant montre comment définir des mesures :

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Mappage de noms de colonne dans CREATE VIEW avec YAML

Lorsque vous créez une vue métrique avec CREATE VIEW et un column_list, le système mappe les colonnes définies par YAML (mesures et dimensions) à la column_list selon la position, et non le nom.

Cela suit le comportement SQL standard, comme illustré dans l’exemple suivant :

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

Dans cet exemple, a mappe à col1, et b mappe à col2, quel que soit leur nom d’origine.

Mettre à niveau votre YAML vers la version 1.1

La mise à niveau d’une vue de métrique vers la version 1.1 de la spécification YAML nécessite des soins, car les commentaires sont gérés différemment des versions antérieures.

Types de commentaires

  • Commentaires YAML (#) : commentaires inline ou monolignes écrits directement dans le fichier YAML à l’aide du symbole #.
  • Commentaires du catalogue Unity : commentaires stockés dans le catalogue Unity pour l’affichage des métriques ou ses colonnes (dimensions et mesures). Elles sont distinctes des commentaires YAML.

Considérations relatives à la mise à niveau

Choisissez le chemin de mise à niveau qui correspond à la façon dont vous souhaitez gérer les commentaires dans votre vue de métrique. Les options suivantes décrivent les approches disponibles et fournissent des exemples.

Option 1 : Conserver les commentaires YAML à l’aide de notebooks ou de l’éditeur SQL

Si votre vue de métrique contient des commentaires YAML (#) que vous souhaitez conserver, procédez comme suit :

  1. Utilisez la ALTER VIEW commande dans un bloc-notes ou un éditeur SQL.

  2. Copiez la définition YAML d’origine dans $$.. Section $$ après AS. Remplacez la valeur de la version par 1.1.

  3. Enregistrez la vue des métriques.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Avertissement

L’exécution ALTER VIEW supprime les commentaires du catalogue Unity, sauf s’ils sont explicitement inclus dans les comment champs de la définition YAML. Si vous souhaitez conserver les commentaires affichés dans le catalogue Unity, consultez l’option 2.

Option 2 : Conserver les commentaires du catalogue Unity

Note

Les instructions suivantes s’appliquent uniquement lors de l’utilisation de la ALTER VIEW commande dans un notebook ou un éditeur SQL. Si vous mettez à niveau votre vue de métrique vers la version 1.1 à l’aide de l’interface utilisateur de l’éditeur YAML, vos commentaires du catalogue Unity sont conservés automatiquement.

  1. Copiez tous les commentaires du catalogue Unity dans les champs appropriés comment de votre définition YAML. Remplacez la valeur de la version par 1.1.

  2. Enregistrez la vue des métriques.

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"


dimensions:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"


measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

Journal des modifications de spécification de version

Version 1.1 (nécessite Databricks Runtime 17.2 ou version ultérieure)

Version 0.1 (nécessite Databricks Runtime 16.4 à 17.1)

  • Version initiale de la spécification YAML de la vue métrique.
  • Last updated on