Conventions de nommage des métriques dans dbt

Le nommage des métriques suit les mêmes patterns que le nommage des modèles dbt, mais les métriques ont leurs propres particularités — notamment la distinction entre les noms de code et les libellés lisibles par l’humain, et la façon dont les différents types de métriques bénéficient de formes de nommage différentes.

Names vs Labels

Le champ name est destiné au code. Le champ label est destiné aux humains. Maintenez-les distincts :

name: revenue_growth_mom
label: "Revenue Growth % M/M"

Les noms utilisent le snake_case, tout en minuscules, sans caractères spéciaux. Ils apparaissent dans les requêtes SQL, les appels d’API et les références de configuration. Ils doivent être des identifiants valides.

Les labels utilisent une capitalisation correcte et peuvent inclure des symboles comme %, / et des abréviations qui ont du sens dans un en-tête de tableau de bord. Les labels sont ce que les utilisateurs finaux voient dans les outils BI qui consomment la couche sémantique.

Un nom comme rev_grw_pct_mm économise quelques caractères mais devient illisible avec le temps. Un label comme revenue_growth_mom rate l’opportunité de présenter une chaîne lisible. Optimisez chaque champ indépendamment.

Patterns par type de métrique

Les différents types de métriques se communiquent mieux avec des formes de nommage différentes :

Type	Pattern	Exemple
Simple	`{noun}_{aggregation}`	`order_count`, `revenue_sum`
Cumulative	`{time_period}_{metric}`	`weekly_active_users`, `mtd_revenue`
Dérivée	`{metric}_growth_{period}`	`revenue_growth_mom`, `orders_growth_yoy`
Ratio	`{numerator}_per_{denominator}`	`revenue_per_customer`, `orders_per_session`
Conversion	`{action}_to_{action}_rate`	`visit_to_buy_rate`, `signup_to_activate_rate`

Ces patterns ne sont pas des règles rigides. L’objectif est que quelqu’un rencontrant un nom de métrique pour la première fois puisse inférer ce qu’elle mesure et comment elle est calculée. mtd_revenue communique immédiatement « revenu month-to-date ». revenue_per_customer est manifestement un ratio. visit_to_buy_rate décrit une étape d’entonnoir.

Les patterns aident également lors du parcours d’une liste de métriques. Quand toutes les métriques cumulatives commencent par une période et que tous les ratios utilisent _per_, on peut visuellement regrouper et filtrer sans lire les descriptions.

Être spécifique

Les noms vagues causent de la confusion. revenue pourrait signifier revenu brut, revenu net ou revenu ajusté. response_time pourrait être en millisecondes ou en secondes. L’ambiguïté s’amplifie à mesure que le nombre de métriques croît.

Mieux vaut :

gross_revenue plutôt que revenue
net_revenue_after_refunds plutôt que net_revenue
response_time_seconds plutôt que response_time
response_time_p95_ms plutôt que p95_response

Une métrique nommée revenue nécessite d’ouvrir la définition pour vérifier de quel revenu il s’agit. Une métrique nommée gross_revenue répond à la question dans le nom.

Quand des agents IA consomment des définitions métriques-as-code, les noms ambigus sont particulièrement problématiques : un copilote interrogé sur le « revenue » choisira la première métrique trouvée, et si cette métrique est ambiguë, la réponse sera incorrecte.

Regrouper les métriques liées avec des préfixes

Utilisez des préfixes cohérents pour créer des familles de métriques :

# Famille revenue
revenue_total
revenue_per_order
revenue_growth_mom
revenue_mtd

# Famille customer
customer_count
customer_lifetime_value
customer_acquisition_cost
customer_retention_rate

Quand quelqu’un recherche « revenue », il trouve toutes les métriques liées aux revenus regroupées. Ce regroupement émerge naturellement de la convention de préfixe — pas de dossiers, de tags ou de métadonnées nécessaires.

Le préfixe doit être l’entité métier, pas la source technique. revenue_total plutôt que orders_revenue_sum. Les utilisateurs pensent en termes métier. Ils cherchent « customer » ou « revenue », pas « orders semantic model ».

Les descriptions ne sont pas optionnelles

Le champ description est la documentation de la métrique. Il répond aux questions auxquelles le nom ne peut pas répondre :

# Que mesure-t-on ?
- name: arr
  type: simple
  type_params:
    measure: arr_value

À comparer avec :

- name: arr
  label: "Annual Recurring Revenue"
  description: >
    Sum of annualized contract values for active subscriptions,
    excluding one-time fees and usage-based charges. Matches
    the finance team's ARR definition as of Q1 2026.
  type: simple
  type_params:
    measure: arr_value

Quand arr inclut des frais ponctuels, la description doit le préciser explicitement — sinon toute personne ayant besoin de le savoir doit chercher ailleurs.

Les bonnes descriptions incluent :

Ce que la métrique mesure en langage clair
Ce qui est exclu ou filtré
La définition de quelle équipe métier elle correspond
Tout détail de calcul non évident

Les descriptions déterminent si un système de métriques-as-code est utilisé avec confiance ou contourné.

La cohérence prime sur l’ingéniosité

La partie la plus difficile du nommage n’est pas de choisir un bon nom — c’est de choisir le même pattern à chaque fois. Une seule métrique nommée monthly_revenue aux côtés d’autres nommées revenue_mom et rev_monthly crée un chaos de navigation.

Choisissez des patterns. Documentez-les. Faites-les respecter en code review. La meilleure convention de nommage est celle que toute l’équipe suit, pas celle qui est théoriquement optimale.