> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer des métriques facturables SQL

Les métriques facturables définies à l'aide de l'éditeur SQL sont formatées comme des requêtes SQL exécutées sur une table appelée `events`, qui inclut tous les événements d'utilisation bruts envoyés à Metronome. De manière similaire à l'éditeur Filtres de base, les requêtes SQL des métriques facturables doivent inclure un ensemble de filtres qui identifient les événements d'utilisation corrects à interroger, et une agrégation pour transformer ces événements en une valeur que Metronome utilisera comme quantité pour les postes en aval.

Metronome gère le filtrage des requêtes SQL pour les clients individuels au cours de leur période de facturation. Vous n'avez pas besoin d'inclure cette logique dans vos requêtes — concentrez-vous simplement sur le filtrage et l'agrégation !

## Fonctionnalités prises en charge

Voici comment vous pouvez accéder aux éléments de votre événement d'utilisation dans la requête :

* Interrogez la table `events`
* Vous pouvez accéder au champ event\_type dans l'éditeur SQL en utilisant `event_type`
* Vous pouvez accéder au champ timestamp dans l'éditeur SQL en utilisant `timestamp`
* Vous pouvez accéder à tout champ dans le dictionnaire properties en utilisant `properties.field_name`

Si votre requête renvoie plus d'une colonne, Metronome recherche d'abord une colonne appelée `value` à utiliser comme colonne pour la quantité de la métrique. Si aucune colonne `value` n'existe, Metronome utilise la première colonne renvoyée dans la requête. Toute autre colonne renvoyée peut être utilisée comme clé de groupe dans la tarification et le packaging en aval.

<Info>
  **INFO**

  Si des colonnes supplémentaires sont renvoyées mais ne sont pas utilisées comme clés de groupe de présentation ou de tarification, Metronome additionne tous les résultats pour générer une quantité unique pour la métrique.
</Info>

## Fonctions et opérateurs pris en charge

L'éditeur SQL prend en charge ces fonctions et opérateurs.

* **Agrégations**
  * `COUNT` : compte le nombre de lignes
  * `SUM` : somme des nombres
  * `MAX` : prend le maximum des nombres
  * `MIN` : prend le minimum des nombres
  * `AVG` : moyenne des nombres
  * `EARLIEST` : retourne la valeur la plus précoce d'une colonne en fonction de son `timestamp`
  * `LATEST` : retourne la dernière valeur d'une colonne en fonction de son `timestamp`
  * `COUNT DISTINCT` : compte les valeurs distinctes dans l'expression
* **Math**
  * `+`, `-`, `*`, `/`
  * `=`, `!=`, `>`, `<`, `≥`, `≤`
  * `LEAST` : retourne le plus petit de ses arguments
  * `GREATEST` : retourne le maximum de ses arguments
  * `ROUND` : arrondit un nombre à un nombre spécifié de décimales
  * `CEIL` : retourne la plus petite valeur entière qui est supérieure ou égale à l'entrée
  * `FLOOR` : retourne la plus grande valeur entière qui est inférieure ou égale à l'entrée
* **Logique**
  * `AND`
  * `OR`
  * `NOT`
  * `CASE WHEN`
  * `IS NULL`
  * `IS NOT NULL`
  * `IN`
  * `NOT IN`
  * `=`
  * `!=`
* **Dates**
  * `DATE_TRUNC` : tronque le champ `timestamp` à l'`hour` ou au `day`.
* **Casting**
  * `CAST`

## Exemple de flux de création

À titre d'exemple d'un scénario plus complexe, utilisez l'éditeur SQL pour créer une métrique facturable qui suit la moyenne quotidienne du stockage utilisé sur une période de facturation.

1. Accédez à la section Métriques facturables dans l'[application Metronome](https://app.metronome.com/).
2. Cliquez sur `+ Ajouter une nouvelle métrique facturable`.
3. Choisissez `Requête SQL`.
4. Nommez votre métrique (par exemple, `Storage latest daily max`).
5. Entrez votre requête SQL :
   ```sql theme={null}
   SELECT SUM(max_daily_storage) / SUM(num_days) as value, user_id, region
   FROM (
       SELECT
           date_trunc('day', timestamp) as date,
           properties.user_id as user_id,
           properties.region as region,
           MAX(properties.storage_used) as max_daily_storage,
           1 as num_days
       FROM events
       WHERE event_type = 'storage_heartbeat'
       GROUP BY date, user_id, region
   )
   GROUP BY user_id, region
   ```

<Info>
  **INFO**

  Dans cet exemple, `user_id` est renvoyé afin qu'il puisse être défini comme `presentation_group_key` lors de la création d'un produit à partir de cette métrique. Cela vous permet d'afficher des factures ventilées par `user_id`. `region` est renvoyé afin qu'il puisse être défini comme `pricing_group_key`. Cela vous permettrait d'ajouter des taux différents pour cette métrique facturable pour les valeurs `us-east-1`, `us-west-1` ou `ap-south-1`.
</Info>

6. Prévisualisez votre métrique par rapport à toutes les données d'utilisation existantes pour vous assurer que les résultats sont corrects. Lorsque c'est terminé, enregistrez votre métrique.

## Granularité de la décomposition SQL

Lorsque vous créez un produit soutenu par une métrique facturable SQL, vous pouvez sélectionner une granularité de décomposition SQL. La valeur par défaut est `hour`, ce qui convient à la plupart des cas d'usage. Avec la granularité `hour`, les coûts sont engagés en continu tout au long de la période de facturation à mesure que l'utilisation est ingérée. Si vous voulez utiliser la dernière valeur d'une métrique, ou si vous avez autrement une métrique qui n'a pas de sens lorsqu'elle est décomposée par heure, vous pouvez utiliser `service period`.

## Exemple

Parcourons un exemple simple pour comparer les deux granularités. Imaginez que vous avez une simple métrique SUM construite à l'aide d'une métrique facturable SQL. Le jour 1 de la période de facturation du client, vous envoyez une valeur de 5. Le jour 2, vous envoyez une valeur de 10. Le jour 3, vous envoyez une valeur de 15. La période de facturation du client s'étend du 01/01/2026 au 01/02/2026.

Avec la granularité de décomposition `hour` par défaut, les coûts sont engagés à mesure que l'utilisation est ingérée :

* En supposant que vous planifiez que le taux est de \$10 du 01/01/2026 au 15/01/2026, et le taux est de \$20 à partir du 15/01/2026, les trois événements seront tarifés à \$10.
* Si vous avez créé un crédit ou un engagement qui s'appliquait uniquement au jour 2 de la période de facturation, seule la valeur d'utilisation de 10 et la dépense correspondante de \$100 seraient appliquées au crédit ou à l'engagement.
* Lorsque vous utilisez le point de terminaison `invoice-breakdowns`, vous verriez une valeur de 5 avec un total de \$50 engagé le jour 1, une valeur de 10 avec un total de \$100 engagé le jour 2, et une valeur de 15 avec un total de \$150 engagé le jour 3.

Si vous définissez plutôt la granularité de décomposition SQL sur `service period`, la quantité totale de 30 utilisations sera engagée à la dernière fenêtre temporelle de la période de facturation :

* Le prix final pour la période de facturation sera utilisé pour la quantité totale. Par exemple, si vous planifiez que le taux est de \$10 du 01/01/2026 au 15/01/2026, et le taux est de \$20 à partir du 15/01/2026, la quantité totale de 30 sera tarifée à \$20.
* Les crédits et engagements doivent couvrir le dernier instant de la période de facturation pour s'appliquer à la dépense.
* Lorsque vous utilisez le point de terminaison `invoice-breakdowns`, les coûts seront engagés à la dernière fenêtre temporelle de la période de facturation.

## Planifier un changement vers ou depuis une métrique facturable SQL sur le produit de contrat

Si vous voulez changer la métrique que vous utilisez pour facturer vos clients, vous pouvez planifier un changement de la métrique facturable associée à un produit d'utilisation. Les métriques facturables SQL sont échangeables sur les produits, et l'échange peut être planifié pour prendre effet à n'importe quel moment d'une période de facturation — pas seulement à une limite de période de facturation.

Parcourons un exemple où nous passons de la métrique facturable A à la métrique facturable B, toutes deux des métriques facturables SQL, à compter du 15/03/2026. Supposons que le client utilise une facturation le 1er du mois.

* La métrique facturable A prend la `avg` sur le champ `value` pour les événements qui correspondent à `average_metric_v1`.
* La métrique facturable B prend la `avg` sur le champ `value_new` pour les événements qui correspondent à `average_metric_v2`.

Nous avons quelques événements d'utilisation qui correspondent à ces métriques facturables :

* Le 01/03/2026, un événement avec une `value` de 4 est ingéré, avec un type d'événement `average_metric_v1`
* Le 02/03/2026, un événement avec une `value` de 6 est ingéré, avec un type d'événement `average_metric_v1`
* Le 15/03/2026, un événement avec une `value_new` de 10 est ingéré, avec un type d'événement `average_metric_v2`
* Le 16/03/2026, un événement avec une `value_new` de 12 est ingéré, avec un type d'événement `average_metric_v2`

Dans la période de facturation de la mise à jour, pendant la période avant que la mise à jour de la métrique facturable ne soit planifiée, nous utilisons uniquement la métrique facturable A :

* Le 01/03/2026, une quantité de 4 est engagée avec son coût correspondant.
* Le 02/03/2026, la moyenne de 4 et 6 est 5. Une quantité de 4 était déjà engagée le jour 1, donc une quantité supplémentaire de 1 est engagée avec son coût correspondant.

Dans la période de facturation de la mise à jour, après la mise à jour de la métrique facturable, nous utilisons une formule pour déterminer quelle est la valeur de la métrique combinée chaque jour :

* La valeur de la métrique facturable B, en utilisant toutes les données d'événements pour la période jusqu'au jour actuel
* plus la valeur de la métrique facturable A, en utilisant toutes les données d'événements jusqu'au jour de l'échange
* moins la valeur de la métrique facturable B, en utilisant toutes les données d'événements jusqu'au jour de l'échange

Cela signifie qu'avec l'exemple ci-dessus :

* Le 15/03/2026, une quantité de 10 est engagée avec son coût correspondant.
* Le 16/03/2026, la moyenne de 10 et 12 est 11. Une quantité de 1 est engagée avec son coût correspondant.

Notez que la troisième partie de la formule, la valeur de la métrique facturable B en utilisant toutes les données d'événements jusqu'au jour de l'échange, est 0 dans ce cas car les deux événements antérieurs ne correspondent pas à la métrique facturable B.