Informations de référence sur la syntaxe YAML de l’affichage des métriques

Cette page explique la grammaire YAML complète pour les vues de métriques. Les définitions d’affichage des métriques suivent la syntaxe de notation YAML standard.

Pour connaître les exigences minimales en matière de version du runtime et de la spécification YAML pour chaque fonctionnalité, consultez la disponibilité des fonctionnalités d’affichage des métriques.

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 :

Origine

Le source champ spécifie la source de données de la vue métrique. Les sources prises en charge incluent des tables, des vues, des vues de métriques et des requêtes SQL. La composabilité s’applique aux vues de métriques. Lorsque vous utilisez une vue de métrique comme source, vous pouvez référencer ses dimensions et ses mesures dans la nouvelle vue de métrique. Consultez Composabilité.

Source de ressource de type table

Référencez une ressource de type table à l’aide de son nom en trois parties :

source: catalog.schema.source_table

Source de requête SQL

Pour utiliser une requête SQL, écrivez le texte de la requête directement dans yaML :

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Filtrer

Un filtre dans la définition YAML s’applique à toutes les requêtes qui référencent la vue de métrique. Écrire des filtres en tant qu’expressions booléennes SQL.

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Joins

Les jointures dans les vues de métriques prennent en charge les jointures directes d’une table de faits à des tables de dimension (schéma en étoile) et des jointures à plusieurs tronçons entre des tables de dimension normalisées (schémas flocons de neige). Vous pouvez également vous joindre à une requête SQL à l’aide d’une SELECT instruction. Consultez Utiliser une requête SQL comme source.

Chaque définition de jointure inclut les champs suivants :

Jointures de schéma en étoile

Dans un schéma en étoile, source est la table des faits et est reliée à une ou plusieurs tables de dimension à l’aide d’un LEFT OUTER JOIN. Les vues de métriques rejoignent les tables de faits et de dimension nécessaires pour la requête spécifique, en fonction des colonnes sélectionnées.

Spécifiez des colonnes de jointure à l’aide d’une clause ou d’une ONUSING clause :

• ON clause : utilise une expression booléenne pour définir la condition de jointure.
• USING clause : répertorie les colonnes portant le même nom dans la table parente et la table jointe.

La jointure doit suivre une relation de plusieurs-à-un. Dans les cas de relations de plusieurs-à-plusieurs, la première ligne correspondante de la table de dimension jointe est sélectionnée.

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

dimensions:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Jointures de schéma Snowflake

Un schéma flocon étend un schéma en étoile en normalisant les tables de dimension et en les connectant à des sous-dimensions. Cela crée une structure de jointure à plusieurs niveaux. Consultez la disponibilité des fonctionnalités d’affichage des métriques pour connaître la configuration minimale requise pour le runtime.

Pour définir un schéma flocon de neige, imbriquez joins à l’intérieur d’une définition de jointure parente :

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

dimensions:
  - name: customer_nation
    expr: customer.nation.n_name

Dimensions

Les dimensions sont des colonnes utilisées dans les clauses SELECT, WHERE et GROUP BY à l'heure de la requête. Chaque expression doit retourner une valeur scalaire. Les dimensions peuvent référencer des colonnes à partir des données sources ou des dimensions définies précédemment dans la vue métrique.

Chaque définition de dimension inclut les champs suivants :

Exemple :

dimensions:
  # Basic dimension
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Dimension with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Dimension with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

Mesures

Les mesures sont des expressions qui produisent des résultats sans niveau prédéfinis d’agrégation. Ils doivent être exprimés à l’aide de fonctions d’agrégation. Pour référencer une mesure dans une requête, utilisez la MEASURE fonction. Les mesures peuvent référencer des champs de base dans les données sources, les dimensions définies précédemment ou les mesures définies précédemment.

Chaque définition de mesure inclut les champs suivants :

Consultez les fonctions d’agrégation pour obtenir la liste des fonctions d’agrégation.

Exemple :

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

Mesures de fenêtre

Le window champ définit des agrégations fenêtrés, cumulatives ou semi-additives pour les mesures. Pour plus d’informations sur les mesures de fenêtre et les cas d’usage, consultez Les mesures de fenêtre.

Chaque spécification de fenêtre comprend les champs suivants :

(1) La dimension référencée doit être déterministe. Les expressions non déterministes telles que rand(), uuid()ou current_timestamp() produisent un ordre de fenêtre imprévisible et peuvent entraîner des résultats d’agrégation incorrects.

Valeurs de range prises en charge

• current: Lignes où la valeur de classement de la fenêtre est égale à la valeur de la ligne actuelle.
• cumulative: toutes les lignes où la valeur de classement des fenêtres est inférieure ou égale à la valeur de la ligne actuelle.
• trailing <value> <unit>: lignes de la ligne actuelle en arrière par les unités de temps spécifiées, par exemple trailing 7 day. N’inclut pas l’unité actuelle.
• leading <value> <unit>: lignes de la ligne actuelle en avance par les unités de temps spécifiées, par exemple leading 3 month. N’inclut pas l’unité actuelle.
• all: toutes les lignes, quelle que soit la valeur de classement de la fenêtre.

Exemple de mesure de fenêtre

L’exemple suivant calcule un nombre de 7 jours propagé de clients uniques :

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

Matérialisation

Le materialization champ configure l’accélération automatique des requêtes à l’aide de vues matérialisées. Pour plus d’informations sur le fonctionnement de la matérialisation, les exigences et les meilleures pratiques, consultez Matérialisation pour les vues de métriques.

Le materialization champ inclut les champs de niveau supérieur suivants :

Chaque entrée materialized_views inclut les champs suivants :

Exemple de matérialisation

L’exemple suivant définit une vue de métrique avec plusieurs matérialisations :

version: 1.1
source: samples.tpch.orders

dimensions:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count

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 dans les backticks. 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

Les exemples suivants montrent comment mettre en forme des références de colonne en fonction des caractères qu’ils contiennent.

Aucun espace

Colonne source : revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

Utilisez des guillemets doubles, des guillemets simples ou pas de guillemets autour du nom de la colonne.

Nom de colonne avec des espaces

Colonne source : `First Name`

expr: '`First Name`'

Utilisez des accents graves comme caractères d’échappement des espaces. Placez l’expression entière entre guillemets doubles.

Noms de colonnes avec des espaces dans une expression SQL

Colonnes sources : `First Name`, `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

Si l’expression ne commence pas par un backtick, les guillemets doubles ne sont pas obligatoires.

Nom de colonne contenant des guillemets

Colonne source : "name"

expr: '`"name"`'

Utilisez des backticks pour échapper les guillemets doubles dans le nom de la colonne. Placez l’expression entre guillemets simples.

Expressions avec deux-points

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

Expressions multilignes

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

Mise à niveau vers YAML 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.
• Commentaires du catalogue Unity : commentaires stockés dans le catalogue Unity pour l’affichage des métriques ou ses colonnes. 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.

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 la $$..$$ section après AS. Remplacez la valeur de version par 1.1.
3. Enregistrez la vue des métriques.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Option 2 : Conserver les commentaires du catalogue Unity

1. Copiez tous les commentaires du catalogue Unity dans les champs appropriés comment de votre définition YAML. Remplacez la valeur de 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"
$$

Pour connaître l’historique des versions de spécification YAML et les exigences minimales du runtime pour chaque fonctionnalité, consultez la disponibilité des fonctionnalités d’affichage des métriques.