Semantic layer and metric definitions

Questa lezione appartiene al binario ml-tabellare: le tabelle ci sono, ma il vero problema è che ognuno le legge a modo suo. Il semantic layer risolve esattamente questo: una sola definizione per ogni numero, condivisa da tutti.

L’idea in una frase

Lo strato semantico fissa una sola definizione condivisa per ogni metrica, così due dashboard non possono mostrare due valori diversi con lo stesso nome. Se il nome è lo stesso, il numero deve essere lo stesso: tutto qui.

Come si procede, in cinque passi

1. Elenca le metriche contestate, quelle con lo stesso nome e valori diversi tra dashboard.
2. Per ciascuna fissa formula, tabella di base, filtri, dimensioni consentite, granularità temporale e responsabile.
3. Descrivi entità, dimensioni e misure di base nei modelli semantici e deriva da lì le metriche semplici, derivate e rapporto.
4. Fai generare le query dallo strato semantico invece di riscrivere la logica in ogni strumento di consumo.
5. Monitora l’adozione contando le definizioni duplicate residue e il tempo speso a riconciliare i numeri tra team.

What is a semantic layer

Lo strato semantico è un’interfaccia tra i dati grezzi o modellati e gli strumenti di consumo come BI, fogli di calcolo e applicazioni. Definisce le metriche, cioè cosa misuri, le dimensioni, cioè come raggruppi, e i percorsi di join, cioè come colleghi le tabelle. Non è una nuova tabella: è un contratto semantico condiviso.

Una definizione di metrica raccoglie tutto ciò che serve a leggere un numero senza ambiguità. Per il ricavo ricorrente mensile, ad esempio, la formula è la somma degli importi di abbonamento. Si calcola sul mart degli abbonamenti dove lo stato vale attivo.

Le dimensioni collegabili sono paese del cliente, tipo di piano e canale di acquisizione. Le granularità temporali vanno dal giorno all’anno. Il responsabile è il team finanza e l’aggiornamento è giornaliero.

Prima dello strato semantico ogni analista riscriveva questa definizione a modo suo. Ora tutti referenziano lo stesso nome con un significato univoco.

MetricFlow in dbt

Nel 2023 dbt ha introdotto uno strato semantico nativo basato su MetricFlow.

Lo compongono tre parti. I modelli semantici in YAML definiscono entità, dimensioni e misure di base. Le metriche, anchesse in YAML, definiscono metriche derivate dalle misure. Il server MetricFlow traduce le richieste in SQL ottimizzato.

Definizione di un modello semantico:

semantic_models:
- name: subscriptions
  model: ref('mrt_finance__subscriptions')
  entities:
    - name: subscription
      type: primary
      expr: subscription_id
    - name: customer
      type: foreign
      expr: customer_id
  dimensions:
    - name: plan_type
      type: categorical
      expr: plan
    - name: customer_country
      type: categorical
      expr: country_code
    - name: subscription_started
      type: time
      type_params:
        time_granularity: month
      expr: started_at
  measures:
    - name: monthly_amount
      description: "Monthly subscription amount in EUR"
      agg: sum
      expr: amount_eur
    - name: active_subscriptions
      description: "Count of active subscriptions"
      agg: count
      expr: 1

Definition of derived metrics:

metrics:
- name: mrr
  description: "Monthly Recurring Revenue"
  label: "MRR"
  type: simple
  type_params:
    measure: monthly_amount
  filter: |
    {{ Dimension('subscription_status') }} = 'active'

- name: arr
  description: "Annualized Run Rate"
  label: "ARR"
  type: derived
  type_params:
    expr: mrr * 12
    metrics:
      - name: mrr

- name: mrr_growth_rate
  description: "MRR growth rate vs same month last year"
  type: ratio
  type_params:
    numerator: mrr - mrr_1y_ago
    denominator: mrr_1y_ago

Con queste definizioni un analista può chiedere il ricavo ricorrente per tipo di piano sugli ultimi dodici mesi senza scrivere SQL, perché MetricFlow genera la query corretta al posto suo.

Perché le definizioni contano

Centralizzare le metriche evita tre danni concreti.

Il primo è reputazionale: numeri divergenti erodono la fiducia nei dati più in fretta di un dato mancante.

Il secondo è finanziario: decisioni prese su definizioni diverse portano a investire nel posto sbagliato.

Il terzo è organizzativo: gli analisti che riconciliano definizioni tra team rubano tempo all’analisi vera.

Il caso tipico è doppio. Vendite e prodotto usano entrambi l’espressione cliente attivo, ma uno conta i contratti aperti e l’altro gli eventi degli ultimi trenta giorni.

Lo strato semantico dichiara granularità, filtri e responsabile e impedisce che la stessa parola porti a due decisioni diverse.

References: dbt Labs (2024), MetricFlow Documentation (2024), Adevinta (2023).

L’errore che lascia due numeri per un nome

Il rischio è usare lo strato semantico come etichetta invece che come processo: grafici senza decisione, metriche senza baseline, conclusioni che non dichiarano le assunzioni critiche. La piattaforma c’è, ma ognuno continua a definire i numeri per conto suo.

La domanda di controllo resta la stessa, cioè quale scelta sbaglieresti se il risultato fosse instabile. Se due dashboard dicono due cose diverse, la scelta è già sbagliata prima di partire.

Verdetto: una metrica, una definizione, un responsabile; se lo stesso nome ha due formule, il problema non è tecnico ma di governo.

Il caso Adevinta

Adevinta, gruppo norvegese che controlla marketplace come Leboncoin, Subito e InfoJobs, ha costruito uno strato semantico unificato sui suoi dati. Ogni paese mappa le proprie strutture su modelli condivisi per annunci, profili e transazioni, e le metriche vengono definite una volta sola. Il tempo per produrre un report confrontabile tra paesi è sceso da 3 giorni a 3 ore e gli errori di riconciliazione sono spariti. È la prova che una definizione condivisa vale più di qualsiasi dashboard veloce.

Domande per metterti alla prova

1. Come risolveresti due dashboard che mostrano valori diversi per la stessa metrica?
2. Quali elementi servono per definire una metrica senza ambiguità?
3. Quando una metrica va modellata come derivata e quando come rapporto?
4. Come misureresti che lo strato semantico sta funzionando per i team?