Semantic layer e metric definitions

Quando termini come “active user”, “revenue” o “conversion” vengono calcolati in modo diverso da una dashboard all’altra, il problema smette di essere tecnico e diventa governance della decisione. Il semantic layer e le metric definitions servono a centralizzare definizioni, granularità e filtri, così che i team possano discutere del business invece che della formula. È una distinzione sottile ma decisiva, perché due numeri divergenti sullo stesso concetto erodono la fiducia più in fretta di un dato mancante.

A cosa serve davvero

Nell’analytics engineering il semantic layer trasforma dati grezzi in modelli testati, documentati e riusabili dal business. Non è teoria isolata: è lo strumento che migliora scelte concrete grazie a dati, assunzioni esplicite e controlli minimi. Se alla fine non sai quale decisione cambia, quale dato osservi e quale errore vuoi evitare, la lezione non è ancora diventata competenza applicata.

Il modello in quattro passi

Lo schema che segue (decisione, dato, controllo, azione) orienta ogni approfondimento tecnico verso un risultato utile.

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

Definire i termini con precisione

Per analizzare il semantic layer conviene fissare prima l’unità di lavoro, che può essere una source, un model, un test, un mart, una metrica o un’esposizione. La colleghi a un segnale osservabile come freshness, lineage, test coverage, costo del modello o fiducia degli stakeholder, e poi dichiari la decisione attesa, che riguarda un modello dbt, il semantic layer, un contratto, un test o la pipeline di release.

Elemento	Specifica richiesta
Unità di analisi	source, model, test, mart, metrica o esposizione
Segnale principale	freshness, lineage, test coverage, costo modello, 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 regge quando un altro analista può ripercorrere la logica, mettere in discussione le assunzioni e arrivare alla stessa decisione.

Cos’è un semantic layer

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

Una definizione di metrica semantica raccoglie tutto ciò che serve a leggere un numero senza ambiguità. Per “monthly_recurring_revenue”, per esempio, la formula è SUM(subscription_amount), calcolata su marts.finance.subscriptions dove status vale ‘active’. Le dimensioni collegabili sono customer_country, plan_type e acquisition_channel, le granularità temporali vanno dal giorno all’anno, il proprietario è il Finance Team e lo SLA di aggiornamento è T+1 ora. Prima del semantic layer ogni analyst riscriveva questa definizione a modo suo. Ora tutti referenziano monthly_recurring_revenue con un significato univoco.

dbt Semantic Layer e MetricFlow

Nel 2023 dbt ha introdotto un semantic layer nativo basato su MetricFlow. Lo compongono tre parti: i Semantic Models in YAML, che definiscono entità, dimensioni e misure di base; le Metrics, anch’esse in YAML, che definiscono metriche derivate dalle misure; e il MetricFlow Server, che traduce le richieste 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 SQL, perché MetricFlow genera la query corretta al posto suo.

Perché le definizioni contano per il business

Centralizzare le metriche evita tre danni concreti. Il primo è reputazionale: numeri divergenti erodono la fiducia nei dati, e dopo incidenti simili servono in media 4 mesi per ricostruirla (dbt Labs 2023). Il secondo è finanziario, perché le decisioni sbagliate costano: il caso Microsoft Bing del 2012 è l’esempio noto, ma lo stesso accade ogni giorno su scala minore. Il terzo è organizzativo: gli analyst spendono il 29% del tempo a riconciliare definizioni tra team, tempo che non va all’analisi.

Caso reale: il semantic layer di Adevinta

Adevinta, gruppo norvegese con marketplace come Leboncoin, Subito e InfoJobs, ha costruito un semantic layer unificato su dbt per tutte le piattaforme. La sfida era unificare le metriche comuni nonostante strutture dati diverse.

La soluzione è passata da semantic models standard per classifieds_listings, user_profiles e transactions. Ogni marketplace mappa i propri dati su questi modelli, e le metriche vengono definite una volta sola. Così “revenue per paese, ultimo trimestre” diventa comparabile tra Subito e Leboncoin nonostante i sistemi di pagamento diversi. Il tempo per un report cross-marketplace è sceso da 3 giorni a 3 ore e gli errori di riconciliazione sono spariti.

Controlli prima di usarlo

Prima di poggiare una decisione sul semantic layer, verifica completezza, duplicati, timezone, definizioni cambiate e segmenti esclusi. Molte analisi falliscono perché il dato misura un comportamento diverso da quello atteso.

Leggere i segmenti, non solo la media

La media aggregata è solo un punto di partenza. Segmenta per canale, coorte, piano, paese, device e maturità utente. Quando due segmenti si muovono in direzioni opposte, la media inganna e porta a decisioni sbagliate.

Chiudere con una scelta

Ogni analisi dovrebbe concludersi con una scelta concreta: continuare, fermare, iterare, investire, rimuovere o approfondire. Se semantic layer e metric definitions non cambiano la decisione, manca il collegamento tra metrica e azione.

Esempio: due “active customer” diversi

Sales e prodotto usano entrambi l’espressione “active customer”, ma uno conta i contratti aperti e l’altro gli eventi negli ultimi 30 giorni. Il semantic layer dichiara grain, filtri e owner, e impedisce così che la stessa parola porti a due decisioni diverse.

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à

Mettere in pratica

Allenati su tre livelli di difficoltà crescente. Comincia con una scheda sintetica del problema: la decisione da supportare, la metrica primaria, la baseline, il rischio principale e l’azione prevista se il segnale è confermato. Al livello intermedio, costruisci una tabella con tre segmenti, periodi o scenari, indicando per ciascuno cosa cambia, una spiegazione plausibile e il controllo da fare prima di raccomandare qualcosa. Per il livello più avanzato, prepara un decision memo completo con ipotesi, dati richiesti, criteri di esclusione, controlli di qualità, soglia decisionale, rischio residuo e piano di monitoraggio.

Come materiale lavora su dbt, warehouse, CRM, eventi, marts, semantic layer e lineage. In mancanza di dati reali, un dataset sintetico di almeno 200 righe con una dimensione temporale, una di segmento e una metrica di outcome è sufficiente.

L’errore tipico

Il rischio è usare “semantic layer e metric definitions” come etichetta invece che come processo. Si riconosce dal grafico senza decisione, dalla metrica senza baseline e dalla conclusione che non dichiara le assunzioni critiche. La domanda di controllo resta la stessa: se il risultato fosse instabile, quale scelta sbaglierei? Quando la risposta non è concreta, il collegamento tra analisi e azione non c’è.

Riepilogo operativo

Il semantic layer e le metric definitions diventano utili solo se producono decisioni più chiare, non se aggiungono terminologia. Il percorso che parte dal problema, attraversa modello e formalizzazione, si appoggia a un esempio reale e si chiude con esercizio e controllo è ciò che trasforma la lezione in una pratica verificabile.

---

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