Techniques avancées pour les vues de métriques

Les techniques avancées pour les vues de métriques vous permettent d’exprimer une logique métier complexe et de réutiliser des définitions dans votre couche sémantique. Cette page explique deux techniques de ce type :

• Mesures de fenêtre : pour les calculs sur des séries temporelles, tels que les moyennes mobiles, les cumuls et les variations d’une période à l’autre.
• Composabilité : pour créer des mesures complexes en référençant d’autres mesures plutôt que de réécrire leur logique.

Cette page suppose une connaissance des concepts de modélisation des vues métriques de base. Consultez les vues des métriques de modèle.

Mesures de fenêtre

Les mesures de fenêtre vous permettent de définir des mesures avec des agrégations fenêtrées, cumulatives ou semi-additives dans vos vues de mesures. Ils prennent en charge les calculs tels que les moyennes mobiles, les changements de période sur période et les totaux en cours d’exécution.

Vous pouvez ajouter une mesure de fenêtre dans l’éditeur de l’Explorateur de catalogues ou dans YAML.

Ajouter une mesure de fenêtre dans l’éditeur

Sous l’onglet Interface utilisateur de l’éditeur d’affichage des métriques, cliquez sur + Fenêtre lors de la modification d’une mesure. + Fenêtre est disponible en mode Générateur et Personnalisé . Les options de fenêtre dans l’éditeur correspondent aux champs YAML décrits dans Définir une mesure de fenêtre.

Pour plus d’informations sur la création et la modification de mesures, consultez Créer une vue de métrique.

Définir une mesure de fenêtre

Une mesure de fenêtre inclut les champs obligatoires suivants :

• order : champ qui détermine l’ordre de la fenêtre.

• plage : définit l’étendue de la fenêtre. Les valeurs current, cumulative, trailing, leading et all sont prises en charge. Pour obtenir une syntaxe et des descriptions complètes, consultez Les valeurs prises en chargerange. Pour plus d’informations sur les modificateurs inclusive et exclusive sur trailing et leading, consultez Inclure ou exclure la ligne d’ancrage.

• semi-additive : spécifie comment agréger la mesure lorsque le champ de commande n’est GROUP BYpas inclus dans la requête. Valeurs possibles : first et last.

Une mesure de fenêtrage prend également en charge le champ facultatif suivant :

• offset : déplace le cadre de la fenêtre vers l’arrière ou l’avant le long du order champ par un intervalle fixe. Utilisez cette option pour les mesures de période sur plusieurs périodes, telles que le mois sur mois ou l’année sur l’année. Pour connaître la syntaxe, les unités prises en charge et les contraintes, consultez Mesures de fenêtre.

Vous pouvez aussi référencer un paramètre entier comme la valeur d’une mesure range de fenêtre ou offset, afin qu’un appelant transmette la taille de la fenêtre au moment de la requête. Voir « Passer une taille de fenêtre » comme paramètre.

Comment offset décaler le cadre de la fenêtre

Consultez la disponibilité des fonctionnalités d’affichage des métriques pour connaître les exigences minimales en matière de version de spécification YAML et de calcul.

Le champ range définit la forme de la fenêtre par rapport à la ligne d’ancrage, et offset fait glisser ce cadre de l’intervalle spécifié le long de order. La table suivante montre la plage de chaque valeur range avec et sans un offset de k, par rapport à la ligne d’ancrage t :

offset est indépendant de semiadditive. Le choix first ou last contrôle toujours la façon dont la mesure est réduite lorsque order ne figure pas dans le GROUP BY de la requête.

Pour de meilleurs résultats, faites correspondre offset au grain naturel de order. Pour les données mensuelles, offset: -12 month est préférable à offset: -365 day car les calculs sur les mois et les années tiennent compte de la durée variable des mois et des années bissextiles, alors que ce n’est pas le cas des calculs avec day.

Inclure ou exclure la ligne d’ancrage

Consultez la disponibilité des fonctionnalités d’affichage des métriques pour connaître les exigences minimales en matière de version de spécification YAML et de calcul.

Pour les plages trailing et leading, le mot-clé facultatif inclusive ou exclusive détermine si la valeur de fenêtre de la ligne d’ancrage (par exemple, aujourd’hui) fait partie de la fenêtre glissante :

L’exemple suivant montre comment inclusive et exclusive affectent la fenêtre glissante pour la date d’ancrage 2025-01-05 avec trailing 3 day.

Supposons que les données sous-jacentes ont une ligne par jour avec les valeurs suivantes :

Chaque modificateur sélectionne les lignes correspondant à trois jours par rapport à l’ancre et en additionne les valeurs :

leading Les plages suivent la même logique en sens inverse.

Exemple de mesure de fenêtre de début, de fin ou de fenêtre dynamique

L’exemple suivant calcule un nombre continu de 7 jours de clients qui ont passé des commandes. Cette métrique suit les tendances de l’engagement client au fil du temps en montrant combien de clients distincts ont effectué des achats pendant la semaine précédant chaque date.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate

measures:
  - name: t7d_customers
    expr: COUNT(DISTINCT o_custkey)
    window:
      - order: date
        range: trailing 7 day
        semiadditive: last

Pour cet exemple, la configuration suivante s’applique :

• order: date spécifie que le champ date ordonne la fenêtre.
• range: trailing 7 day définit la fenêtre comme étant les 7 jours avant chaque date, à l’exclusion de la date elle-même.
• semiadditive: last retourne la dernière valeur dans la fenêtre de 7 jours quand date n’est pas une colonne de regroupement.

CREATE OR REPLACE VIEW catalog.schema.rolling_customers WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1

  source: samples.tpch.orders
  filter: o_orderdate > DATE'1998-01-01'

  fields:
    - name: date
      expr: o_orderdate

  measures:
    - name: t7d_customers
      expr: COUNT(DISTINCT o_custkey)
      window:
        - order: date
          range: trailing 7 day
          semiadditive: last
$$

Exemple de mesure de fenêtre d’une période à l’autre

L’exemple suivant calcule la croissance des ventes quotidiennes en comparant le chiffre d’affaires d’aujourd’hui (somme de tous les prix de commande) au chiffre d’affaires d’hier. Cette métrique identifie les tendances quotidiennes des ventes et montre le pourcentage de variation du chiffre d’affaires.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
measures:
  - name: previous_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: trailing 1 day
        semiadditive: last
  - name: current_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: current
        semiadditive: last
  - name: day_over_day_growth
    expr: (MEASURE(current_day_sales) - MEASURE(previous_day_sales)) / MEASURE(previous_day_sales) * 100

Pour cet exemple, la configuration suivante s’applique :

• L'exemple utilise deux mesures de fenêtre : une pour calculer le total des ventes le jour précédent et l’autre pour le jour actuel.
• Une troisième mesure calcule la variation du pourcentage (croissance) entre les jours actuels et les jours précédents.

Exemple de mesure de fenêtre d’une année sur l’autre à l’aide de offset

Le offset modificateur est le bloc de construction pour les mesures d’une période à l’autre. Définissez une copie décalée d’une mesure de base, puis composez les deux pour exprimer des deltas, des ratios ou des taux de croissance directement dans la vue des métriques.

L’exemple suivant calcule la croissance des ventes annuelles en comparant les ventes de chaque mois au même mois de l’année précédente. La mesure différée utilise offset: -12 month pour remonter 12 mois en arrière dans le champ month.

version: 1.1
source: main.default.monthly_sales

fields:
  - name: month
    expr: month
  - name: category
    expr: category

measures:
  - name: monthly_sales
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last

  - name: monthly_sales_py
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last
        offset: -12 month

  - name: yoy_growth
    expr: MEASURE(monthly_sales) - MEASURE(monthly_sales_py)

  - name: yoy_growth_pct
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0)

Pour cet exemple, la configuration suivante s’applique :

• monthly_sales est la mesure de base, additionnant les ventes pour le mois en cours.
• monthly_sales_py est la même mesure décalée de 12 mois en arrière à l’aide de offset: -12 month. Pour janvier 2025, elle retourne la valeur de janvier 2024.
• yoy_growth et yoy_growth_pct composez les deux mesures pour exprimer le changement absolu et de pourcentage. L’utilisation NULLIF évite les erreurs de division par zéro lorsque la valeur de l’année précédente est égale à zéro.

Exemple de mesure de total cumulatif progressif

L’exemple suivant calcule le chiffre d’affaires cumulé du début du jeu de données jusqu’à chaque date. Ce total en cours d’exécution montre combien le chiffre d’affaires total a été généré au fil du temps, utile pour suivre les progrès vers les objectifs annuels de chiffre d’affaires ou analyser les modèles de croissance à long terme.

version: 1.1
source: samples.tpch.orders

filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: customer
    expr: o_custkey

measures:
  - name: running_total_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last

Pour cet exemple, la configuration suivante s’applique :

• order: date trie la fenêtre par ordre chronologique.
• range: cumulative définit la fenêtre comme l’ensemble des données depuis le début du jeu de données jusqu’à chaque date incluse.
• semiadditive: last retourne la valeur cumulative la plus récente lorsqu’elle date n’est pas incluse dans les données de GROUP BYla requête, au lieu de la somme de toutes les dates.

Exemple de mesure de cumul périodique jusqu’à ce jour

L’exemple suivant calcule le chiffre d’affaires depuis le début de l'année (YTD). Cette mesure montre le chiffre d’affaires cumulé généré du 1er janvier de chaque année jusqu’à ce jour, réinitialisée au début de chaque nouvelle année.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1997-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)
measures:
  - name: ytd_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last
      - order: year
        range: current
        semiadditive: last

Pour cet exemple, la configuration suivante s’applique :

• L’exemple utilise deux spécifications de fenêtre : une pour la somme cumulative sur le date champ et une autre pour limiter la somme à l’année current .
• Le year champ limite la somme cumulative afin qu’elle soit réinitialisée au début de chaque nouvelle année.
• Les champs month et year forment une hiérarchie de dates sur le champ de commande date : chacun est défini sur le champ date par son nom, et non sur la colonne o_orderdate sous-jacente, afin que les requêtes puissent regrouper cette mesure en fonction d’eux. Voir Regrouper par champ de hiérarchie de dates.

Exemple de mesure semi-additive

L’exemple suivant calcule les soldes de compte, qui ne doivent pas être additionnés entre les dates (vous ne pouvez pas ajouter le solde du lundi au solde du mardi pour obtenir le solde total). Au lieu de cela, lors de l’agrégation sur plusieurs jours, la mesure retourne le solde le plus récent. Toutefois, la mesure peut toujours être additionnée entre les clients pour afficher le solde total sur tous les comptes un jour donné.

version: 1.1

fields:
  - name: date
    expr: date
  - name: customer
    expr: customer_id

measures:
  - name: semiadditive_balance
    expr: SUM(balance)
    window:
      - order: date
        range: current
        semiadditive: last

Pour cet exemple, la configuration suivante s’applique :

• order: date trie la fenêtre par ordre chronologique.
• range: current limite la fenêtre à un seul jour sans agrégation sur plusieurs jours.
• semiadditive: last retourne le solde le plus récent lors de l’agrégation sur plusieurs jours.

Interroger une mesure de fenêtre

Vous pouvez interroger une vue métrique avec une mesure de fenêtre comme n’importe quelle autre vue métrique. Une mesure de fenêtre est calculée le long de son order champ. Par conséquent, une requête qui décompose les résultats au fil du temps doit référencer ce champ, directement ou via un champ de hiérarchie de dates défini sur celui-ci. Lorsque la requête ne référence pas le champ d’ordre, le semiadditive mot clé détermine la valeur retournée, comme décrit dans l’exemple de mesure Semiadditive.

L’exemple suivant regroupe une mesure de fenêtre selon state et selon une expression de mois sur le champ de commande date :

SELECT
   state,
   DATE_TRUNC('month', date),
   MEASURE(t7d_customers) as m
FROM my_metric_view
WHERE date >= DATE'2024-06-01'
GROUP BY ALL

Regrouper par champ de hiérarchie de dates

Une hiérarchie de dates agrège le champ de tri à des niveaux de granularité plus élevés, tels que la semaine, le mois ou l’année. Définissez chaque niveau en tant que champ sur le champ de commande par nom, et non sur la colonne source sous-jacente :

fields:
  - name: date
    expr: o_orderdate
  # Date hierarchy: each level is defined on the order field `date`,
  # not on the underlying o_orderdate column.
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)

Le regroupement d’une mesure de fenêtre selon un niveau de hiérarchie renvoie la mesure à ce fragment. En supposant que l’exemple de période à ce jour soit créé sous la forme ytd_metric_view, comme dans l’exemple de mesure de période à ce jour, la requête suivante renvoie la valeur YTD à la dernière date de chaque mois :

SELECT month, MEASURE(ytd_sales) AS ytd_sales
FROM ytd_metric_view
GROUP BY month
ORDER BY month;

Composabilité

Les vues de métriques peuvent être composées. Vous pouvez créer de nouveaux champs et mesures qui référencent des champs existants plutôt que de réécrire la logique à partir de zéro. Cela réduit la duplication et facilite la maintenance des définitions de métriques complexes.

La composabilité fonctionne à deux niveaux : au sein d’une vue de métrique unique et entre les vues de métriques quand une vue de métrique est utilisée comme source pour une autre.

La composabilité prend en charge les modèles de référence suivants :

• Champs antérieurs dans de nouveaux champs.
• Champs et mesures antérieures dans de nouvelles mesures.
• Les champs issus des vues de métriques utilisés comme source dans de nouveaux champs.
• Champs et mesures des vues de métriques servant de source à de nouvelles mesures.

Définir des mesures avec la composabilité

Dans la measures section, vous pouvez référencer des mesures à partir de la vue de métrique source ou des mesures définies précédemment dans la même vue de métrique. Cette approche améliore la cohérence, l’auditabilité et la maintenance de votre couche sémantique.

Exemple : Valeur de commande moyenne (AOV)

L’exemple suivant définit la valeur moyenne de l’ordre (AOV) à l’aide de deux mesures atomiques : total_revenue (somme des prix de commande) et order_count (nombre de commandes). La avg_order_value mesure fait référence aux deux mesures atomiques.

version: 1.1

source: samples.tpch.orders

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

  # Order Count
  - name: order_count
    expr: COUNT(1)

  # Composed Measure: Average Order Value (AOV)
  - name: avg_order_value
    # Defines AOV as Total Revenue divided by Order Count
    expr: MEASURE(total_revenue) / MEASURE(order_count)

Si la total_revenue définition change (par exemple, pour exclure la taxe), avg_order_value utilise automatiquement la définition mise à jour.

Composabilité avec une logique conditionnelle

Vous pouvez utiliser la composabilité pour créer des ratios complexes, des pourcentages conditionnels et des taux de croissance sans compter sur les fonctions de fenêtre pour des calculs simples sur période.

Exemple : Taux de traitement

L’exemple suivant calcule le taux de traitement : pourcentage de commandes avec état 'F' (rempli). La mesure divise les commandes remplies par le total des commandes.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Orders (denominator)
  - name: total_orders
    expr: COUNT(1)

  # Fulfilled Orders (numerator)
  - name: fulfilled_orders
    expr: COUNT(1) FILTER (WHERE o_orderstatus = 'F')

  # Composed Measure: Fulfillment Rate (Ratio)
  - name: fulfillment_rate
    expr: MEASURE(fulfilled_orders) / MEASURE(total_orders)
    format:
      type: percentage

Meilleures pratiques pour la composabilité

1. Définissez d’abord les mesures atomiques : établissez des mesures fondamentales (SUM, COUNT, AVG) avant de définir des mesures qui les référencent.
2. Utiliser MEASURE() pour les références : utilisez la MEASURE() fonction lors du référencement d’une autre mesure dans un expr. Ne répétez pas manuellement la logique d’agrégation. Par exemple, évitez SUM(a) / COUNT(b) si des mesures pour les deux valeurs existent déjà.
3. Hiérarchiser la lisibilité : composez des mesures à l’aide de formules mathématiques claires. Par exemple, MEASURE(gross_profit) / MEASURE(total_revenue) il est plus clair qu’une seule expression SQL complexe.
4. Ajouter des métadonnées sémantiques : utilisez des métadonnées sémantiques pour mettre en forme des mesures composées (par exemple, des pourcentages ou des devises) pour les outils en aval. Consultez les métadonnées de l’agent dans les vues de métriques.

Ressources supplémentaires

• Vues des métriques du modèle
• Métadonnées de l’agent dans les vues de métrique
• Matérialisation pour les vues métriques
• Informations de référence sur la syntaxe YAML de l’affichage des métriques