Semantic layer and 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.

Phase	What to clarify	Output
Question	Which real choice needs improvement?	Decision to make
Measure	Which observable signal represents the problem?	Metric or source data
Control	Which baseline makes the result interpretable?	Credible comparison
Action	What changes after the analysis?	Next operational step

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.

Element	Requested specification
Unit of analysis	source, model, test, mart, metric or exposure
Primary signal	freshness, lineage, test coverage, costo modello, fiducia stakeholder
Baseline	Previous period, comparable group, benchmark, or counterfactual scenario
Decision	dbt model, semantic layer, contract, test or release pipeline
Risk	Mistaking an available number for sufficient proof

La formalizzazione regge quando un altro analista può ripercorrere la logica, mettere in discussione le assunzioni e arrivare alla stessa decisione.

What is a 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 and 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.

Definition of a 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

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 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.

Real case: Adevinta's semantic layer

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.

Observed evidence	Cautious interpretation	Recommended action
The number improves	Could be a real effect or normal variation	Look for comparison and segment
One segment changes more than others	The aggregated average hides a difference	Separate cohorts or use cases
Cost grows along with the result	Impact must be read on the margin	Estimate trade-offs and sustainability

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’è.

Operational Summary

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.

---

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