La timespine MetricFlow est un modèle dbt qui contient une ligne par jour sur une plage de dates. MetricFlow l’utilise comme ancre de date fiable pour les métriques cumulatives et pour combler les lacunes dans la sortie des séries temporelles.
Elle n’est pas optionnelle si l’on prévoit d’utiliser des métriques cumulatives ou le paramètre join_to_timespine. MetricFlow s’attend à ce que la table existe, et les requêtes qui en ont besoin échoueront sans elle.
Créer le modèle timespine
Créez un modèle dbt appelé metricflow_time_spine.sql :
{{ config(materialized='table') }}
{{ dbt.date_spine( datepart="day", start_date="CAST('2020-01-01' AS DATE)", end_date="CAST('2030-12-31' AS DATE)") }}La macro dbt.date_spine fait partie de la bibliothèque de macros cross-database de dbt Core. Elle génère une ligne par unité datepart entre start_date et end_date. Le résultat est une seule colonne date_day avec une séquence continue de dates.
Matérialisez-la en table, pas en vue. MetricFlow effectue souvent des jointures contre elle, et une vue ré-exécute la logique de génération de dates à chaque requête. La matérialisation en table est moins coûteuse et plus rapide.
Exécutez-la explicitement lors de la première configuration de la couche sémantique :
dbt build -s metricflow_time_spineLa configurer dans dbt_project.yml
Après la création du modèle, indiquez à MetricFlow quelle colonne utiliser :
semantic-layer: time_spine: standard_granularity_column: date_dayLe standard_granularity_column doit correspondre au nom de colonne produit par le modèle timespine. Avec dbt.date_spine, cette colonne est date_day.
Quand MetricFlow utilise la timespine
MetricFlow a recours à la timespine dans deux situations.
La première est celle des métriques cumulatives avec un paramètre window. Une métrique comme « utilisateurs actifs glissants sur 7 jours » nécessite une séquence continue de dates pour définir ce que « les 7 derniers jours » signifie pour chaque point de données. Sans timespine, MetricFlow n’a pas d’ancre pour effectuer le calcul glissant. Les requêtes généreront des erreurs.
metrics: - name: weekly_active_users type: cumulative type_params: measure: active_users window: 7 daysLa seconde est le paramètre join_to_timespine sur les mesures. Quand une métrique a des jours sans données sous-jacentes, le comportement par défaut est de ne retourner aucune ligne pour ce jour. Si l’on veut un zéro à la place, on a besoin à la fois de join_to_timespine et de fill_nulls_with :
measures: - name: daily_revenue agg: sum expr: order__amount join_to_timespine: true fill_nulls_with: 0Sans join_to_timespine, un graphique de revenus quotidiens aura des lacunes pour les jours sans commandes. Ces lacunes ressemblent souvent à des données manquantes plutôt qu’à des jours à zéro activité, ce qui perturbe les utilisateurs en aval et casse les rapports automatisés qui attendent une ligne pour chaque date.
La distinction entre join_to_timespine: true avec et sans fill_nulls_with importe. La jointure avec la timespine garantit que chaque date apparaît. fill_nulls_with définit la valeur à afficher pour les dates sans données. Pour le revenu, zéro est généralement correct. Pour une métrique où null et zéro ont des significations différentes (par exemple, une lecture de capteur où l’absence de mesure est différente d’une mesure à zéro), on pourrait vouloir join_to_timespine sans fill_nulls_with.
Plage de dates et maintenance
Définissez la date de début avant les données les plus anciennes et la date de fin suffisamment loin dans le futur pour ne pas avoir à la mettre à jour constamment. Commencer à 2020-01-01 et finir à 2030-12-31 couvre la plupart des projets pendant plusieurs années.
Quand la plage doit être étendue, mettez à jour l’appel de macro et ré-exécutez dbt build -s metricflow_time_spine. Le modèle est petit — une décennie de dates quotidiennes représente environ 3 650 lignes — donc sa reconstruction est rapide.
La timespine n’a pas besoin de couvrir exactement la même plage que les données. Si la commande la plus ancienne date de 2022, une timespine commençant en 2020 fonctionne très bien. MetricFlow ne fait des jointures que sur les dates qui apparaissent dans les résultats de requête.
Utiliser une colonne timespine personnalisée
Si une table de dimension de dates existe déjà dans le projet, MetricFlow peut y être pointé au lieu de générer un nouveau modèle. L’exigence est une colonne avec une ligne par jour à la granularité configurée. La colonne doit être nommée exactement comme spécifié dans standard_granularity_column.
Pour les projets nécessitant une granularité inférieure à la journée (métriques horaires), MetricFlow supporte la configuration d’une timespine de granularité plus élevée avec un datepart hour ou minute. Cette timespine est configurée en parallèle de la timespine journalière standard.
La plupart des projets n’ont besoin que de la timespine journalière. Pour les tableaux de bord opérationnels avec une granularité horaire, il faudrait configurer un modèle timespine supplémentaire à la granularité appropriée et le référencer séparément dans dbt_project.yml.