Semantic layer e metric definitions

Quando “active user”, “revenue” o “conversion” vengono calcolati in tre dashboard diverse, il problema non è solo tecnico: è governance della decisione. Semantic layer e metric definitions centralizza definizioni, grain e filtri in modo che i team discutano del business, non della formula.

Una scena da cui partire

Leggi questa lezione come disegno del linguaggio metrico comune. Una definizione riusabile deve dichiarare grain, filtri, owner, validità e casi in cui non va usata.

• Contesto: Quale intuizione deve restare dopo la lettura?
• Metodo: Quale esempio rende concreto il concetto?
• Applicazione: Quale errore diventa più facile evitare?

Cos’è un semantic layer

Il semantic layer è un’interfaccia tra i dati grezzi/modellati e gli strumenti di consumo (BI, AI, fogli di calcolo). Definisce metriche (cosa misuri), dimensioni (come le raggruppi), e join paths (come colleghi le tabelle). Non è una nuova tabella: è un contratto semantico.

Esempio di metrica come definizione semantica:

Metrica: "monthly_recurring_revenue"
- Formula: SUM(subscription_amount)
- Dove: marts.finance.subscriptions WHERE status = 'active'
- Dimensioni collegabili: customer_country, plan_type, acquisition_channel
- Granularità temporali: day, week, month, quarter, year
- Proprietario: Finance Team
- SLA di aggiornamento: T+1 ora

Prima del semantic layer, ogni analyst riscriveva questa definizione nella propria query. Dopo, tutti referenziano monthly_recurring_revenue e sanno che significa esattamente questo.

dbt Semantic Layer e MetricFlow

dbt ha introdotto il Semantic Layer nativo nel 2023, basato su MetricFlow (acquisizione di Transform). L’architettura ha tre componenti:

1. Semantic Models (YAML) — definiscono entità, dimensioni e misure di base
2. Metrics (YAML) — definiscono le metriche derivate da misure
3. MetricFlow Server — traduce richieste (es. “MRR per paese, ultimi 6 mesi”) in SQL ottimizzato

Definizione di un semantic model:

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

Definizione di metriche derivate:

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 analyst può chiedere “MRR per plan_type, ultimi 12 mesi” senza scrivere una riga di SQL. MetricFlow traduce in SQL, applica i join corretti, e restituisce il risultato.

Perché le metric definitions contano per il business

L’impatto va oltre l’efficienza tecnica. Le metriche centralizzate prevengono tre tipi di danno:

1. Danno reputazionale: numeri diversi in report diversi erodono la fiducia nei dati. Dopo un incidente di metriche divergenti, le aziende impiegano in media 4 mesi per ricostruire la fiducia degli stakeholder (fonte: survey dbt Labs 2023).

2. Danno finanziario: decisioni basate su metriche errate costano. Il caso Microsoft Bing del 2012 (42 milioni di revenue stimato vs -0.8% reale) è un classico, ma succede ogni giorno in scala minore: budget marketing allocati male perché il ROAS è calcolato in modo diverso da team a team.

3. Danno organizzativo: il tempo che analyst passano a dibattere definizioni è tempo sottratto all’analisi. Il sondaggio dbt ha rilevato che gli analyst passano in media il 29% del tempo a “riconciliare definizioni di metriche tra team”.

Caso reale: il semantic layer di Adevinta

Adevinta, il gruppo norvegese che possiede marketplace come Leboncoin (Francia), Subito (Italia), e InfoJobs (Spagna), ha costruito un semantic layer unificato su dbt per tutte le sue piattaforme. La sfida era unificare metriche comuni (listings, utenti, revenue) attraverso marketplace con strutture dati diverse.

Il team ha creato semantic models standard per:

• classifieds_listings (annunci): entità comune a tutte le piattaforme
• user_profiles (profili utente)
• transactions (pagamenti)

Ogni marketplace mappa i propri dati sui semantic models standard, ma le metriche sono definite una volta sola in YAML. Una query per “revenue per paese, ultimo trimestre” produce risultati comparabili tra Subito e Leboncoin, anche se i sistemi di pagamento sottostanti sono diversi (Stripe in Francia, Adyen in Italia).

Adevinta ha pubblicato un case study sulla migrazione: il tempo per costruire un nuovo report cross-marketplace è sceso da 3 giorni a 3 ore, e gli errori di riconciliazione tra paesi sono spariti perché “la definizione è una sola, il dato sorgente può essere diverso, ma la metrica è la stessa”.

---

Riferimenti:

• dbt Labs. (2024). “What is the dbt Semantic Layer?” dbt Documentation.
• MetricFlow Documentation. (2024). “Semantic Models and Metrics.”
• Adevinta. (2023). “Building Cross-Marketplace Analytics with dbt.” Coalesce Conference.

Controllo di qualità

Prima di usare semantic layer e metric definitions in una decisione, controlla sempre completezza, duplicati, timezone, definizioni cambiate e segmenti esclusi. Molte analisi apparentemente sofisticate falliscono perché il dato di partenza misura un comportamento diverso da quello che il team crede di osservare.

Interpretazione per segmenti

La media aggregata è solo il punto di partenza. Segmenta per canale, coorte, piano, paese, device e maturità dell’utente. Se due segmenti si muovono in direzioni opposte, la media non rappresenta nessuno dei due e può portare a una decisione sbagliata.

Decisione operativa

Ogni analisi deve terminare con una scelta possibile: continuare, fermare, iterare, investire, rimuovere o approfondire. Se semantic layer e metric definitions non cambia una decisione, probabilmente manca ancora il collegamento tra metrica e azione.

Problema reale

Nel dominio di analytics engineering, Semantic layer e metric definitions serve a risolvere questo problema: trasformare dati grezzi in modelli testati, documentati e riusabili dal business. La lezione non va trattata come teoria isolata, ma come un modo per migliorare una scelta concreta con dati, assunzioni esplicite e controlli minimi.

Obiettivo operativo: Comprendere il problema analitico e il contesto decisionale; Applicare esempi, metriche e controlli a casi reali. Se alla fine non sai indicare quale decisione cambia, quale dato osservi e quale errore vuoi evitare, la lezione non è ancora diventata competenza applicata.

Modello concettuale

Fase	Cosa chiarire	Output
Domanda	Quale scelta reale deve migliorare?	Decisione da prendere
Misura	Quale segnale osservabile rappresenta il problema?	Metrica o dato sorgente
Controllo	Quale baseline rende il risultato interpretabile?	Confronto credibile
Azione	Che cosa cambia dopo l’analisi?	Prossimo passo operativo

Il modello concettuale è intenzionalmente semplice: decisione, dato, controllo, azione. Ogni approfondimento tecnico deve rafforzare almeno uno di questi quattro punti.

Formalizzazione rigorosa

Per rendere Semantic layer e metric definitions analizzabile, definisci prima l’unità di lavoro: source, model, test, mart, metrica o esposizione. Poi collega questa unità a una metrica osservabile: freshness, lineage, test coverage, costo modello e fiducia stakeholder. Infine dichiara la decisione attesa: modello dbt, semantic layer, contratto, test o pipeline di release.

Elemento	Specifica richiesta
Unità di analisi	source, model, test, mart, metrica o esposizione
Segnale principale	freshness, lineage, test coverage, costo modello e fiducia stakeholder
Baseline	Periodo precedente, gruppo comparabile, benchmark o scenario controfattuale
Decisione	modello dbt, semantic layer, contratto, test o pipeline di release
Rischio	Scambiare un numero disponibile per una prova sufficiente

La formalizzazione e solida quando un altro analista può riprodurre la logica, criticare le assunzioni e ottenere la stessa decisione partendo dagli stessi dati.

Esempio o caso studio

Sales e prodotto usano entrambi “active customer”, ma uno conta contratti aperti e l’altro eventi negli ultimi 30 giorni. Il semantic layer evita che la stessa parola porti a due decisioni diverse, dichiarando grain, filtri e owner della metrica.

Evidenza osservata	Lettura prudente	Azione consigliata
Il numero migliora	Potrebbe essere effetto reale o variazione normale	Cercare confronto e segmento
Un segmento cambia più degli altri	La media aggregata nasconde una differenza	Separare coorti o casi d’uso
Il costo cresce insieme al risultato	L’impatto va letto sul margine	Stimare trade-off e sostenibilità

Lab / esercizio

Livello base

Scrivi una scheda di una pagina per Semantic layer e metric definitions: decisione da supportare, metrica primaria, baseline, rischio principale e azione se il segnale e confermato.

Livello intermedio

Costruisci una tabella con tre segmenti, periodi o scenari. Per ciascuno indica cosa cambia, quale spiegazione alternativa e plausibile e quale controllo useresti prima di raccomandare un azione.

Livello research-grade

Prepara un decision memo: ipotesi, dati richiesti, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio dopo la decisione.

Dataset e materiali consigliati

Usa dbt, warehouse, sorgenti CRM, eventi, marts, semantic layer e lineage. Se non hai accesso a dati reali, crea un dataset sintetico con almeno 200 righe, una dimensione temporale, una dimensione segmento e una metrica di outcome.

Errore tipico da evitare

L’errore più comune e usare Semantic layer e metric definitions come etichetta invece che come processo. Succede quando il team mostra un grafico senza decisione, una metrica senza baseline, o una conclusione senza indicare quale assunzione potrebbe invalidarla.

La domanda di controllo è: se questo risultato fosse instabile, quale scelta sbaglierei? Se la risposta non è concreta, manca ancora il collegamento tra analisi e azione.

Quiz o checkpoint

1. Quale decisione concreta dovrebbe migliorare questa lezione?
2. Quale unità di analisi rende il problema misurabile?
3. Quale baseline useresti per evitare una lettura ingenua?
4. Quale errore tipico potrebbe cambiare la conclusione?
5. Quale output consegneresti a uno stakeholder non tecnico?

Riepilogo operativo

Semantic layer e metric definitions diventa utile quando produce una decisione più chiara, non quando aggiunge terminologia. Usa il framework problema, modello, formalizzazione, esempio, lab e checkpoint per trasformare la lezione in pratica verificabile. Categoria: Analisi. Difficoltà: advanced. Tempo stimato: 18 min.