Tecniche avanzate per le visualizzazioni delle metriche

Le tecniche avanzate per le visualizzazioni delle metriche consentono di esprimere logica di business complessa e riutilizzare le definizioni nel livello semantico. Questa pagina illustra due tecniche di questo tipo:

• Misure di finestra: per calcoli su serie temporali, ad esempio medie mobili, totali cumulativi e variazioni tra periodi.
• Componibilità: per la creazione di misure complesse facendo riferimento ad altre misure anziché riscrivere la logica.

Questa pagina presuppone la familiarità con i concetti di modellazione della visualizzazione delle metriche di base. Vedere Visualizzazioni delle metriche del modello.

Misure della finestra

Le misure finestra consentono di definire misure con aggregazioni finestrate, cumulative o semiadditive nelle visualizzazioni delle metriche. Supportano calcoli come medie mobili, variazioni da un periodo all'altro e totali progressivi.

È possibile aggiungere una misura della finestra nell'editor di Esplora cataloghi o in YAML.

Aggiungere una misura finestra nell'editor

Nella scheda interfaccia utente dell'editor di visualizzazione metriche fare clic su + Finestra durante la modifica di una misura. + Window è disponibile sia in modalità Builder che in modalità personalizzata. Le opzioni della finestra nell'editor corrispondono ai campi YAML descritti in Definire una misura della finestra.

Per altre informazioni sulla creazione e la modifica di misure, vedere Creare una visualizzazione delle metriche.

Definire una misura finestra

Una misura finestra include i campi obbligatori seguenti:

• order: campo che determina l'ordinamento della finestra.

• range: definisce l'extent della finestra. Tra i valori supportati sono inclusi current, cumulative, trailing, leading e all. Per la sintassi completa e le descrizioni, vedere Valori supportatirange. Per i dettagli sui modificatori inclusive e exclusive su trailing e leading, vedere Includere o escludere la riga di ancoraggio.

• semiadditive: specifica come aggregare la misura quando il campo dell'ordine non è incluso nella GROUP BYquery. Valori possibili: first e last.

Una misura finestra supporta anche il campo facoltativo seguente:

• offset: sposta la cornice della finestra indietro o avanti lungo il order campo in base a un intervallo fisso. Usa questa opzione per le misure da un periodo all’altro, ad esempio da un mese all’altro o da un anno all’altro. Per la sintassi, le unità supportate e i vincoli, vedere Misure finestra.

Come offset sposta la cornice della finestra

Per i requisiti minimi di calcolo e di versione delle specifiche YAML, vedere Disponibilità delle funzionalità di visualizzazione delle metriche .

Il range campo definisce la forma della finestra rispetto alla riga di ancoraggio e offset scorre tale cornice in base all'intervallo specificato lungo order. La tabella seguente mostra il frame per ogni valore range con e senza un offset di k, relativo alla riga di ancoraggio t:

offset è indipendente da semiadditive. La scelta first o last continua comunque a controllare il modo in cui la misura si comprime quando order non è presente nel campo GROUP BY della query.

Per ottenere risultati ottimali, abbina offset alla venatura naturale di order. Per i dati mensili, offset: -12 month è preferibile a offset: -365 day poiché l'aritmetica relativa a mesi e anni rispetta la diversa durata dei mesi e gli anni bisestili, mentre l'aritmetica di day non lo fa.

Includere o escludere la riga di ancoraggio

Per i requisiti minimi di calcolo e di versione delle specifiche YAML, vedere Disponibilità delle funzionalità di visualizzazione delle metriche .

Per gli intervalli trailing e leading, la parola chiave facoltativa inclusive o exclusive controlla se il valore della finestra della riga di ancoraggio (ad esempio, oggi) fa parte della finestra mobile:

L'esempio seguente mostra come inclusive e exclusive influiscono sulla finestra mobile per la data di ancoraggio 2025-01-05 con trailing 3 day.

Si supponga che i dati sottostanti dispongano di una riga al giorno con i valori seguenti:

Ogni modificatore seleziona tre giorni di righe relative all'ancoraggio e somma i relativi valori:

leading gli intervalli seguono la stessa logica nella direzione opposta.

Esempio di misura finestra arretrata, mobile o avanzata

Nell'esempio seguente viene calcolato un conteggio mobile su 7 giorni dei clienti che hanno effettuato ordini. Questa metrica tiene traccia delle tendenze di engagement dei clienti nel tempo mostrando il numero di clienti distinti che hanno effettuato acquisti nella settimana fino a ogni data.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate

measures:
  - name: t7d_customers
    expr: COUNT(DISTINCT o_custkey)
    window:
      - order: date
        range: trailing 7 day
        semiadditive: last

Per questo esempio, si applica la configurazione seguente:

• order: date specifica che il date campo ordina la finestra.
• range: trailing 7 day definisce la finestra come i 7 giorni precedenti a ogni data, escludendo la data stessa.
• semiadditive: last restituisce l'ultimo valore nella finestra di 7 giorni quando date non è una colonna di raggruppamento.

CREATE OR REPLACE VIEW catalog.schema.rolling_customers WITH METRICS LANGUAGE YAML AS
$$
  version: 1.1

  source: samples.tpch.orders
  filter: o_orderdate > DATE'1998-01-01'

  fields:
    - name: date
      expr: o_orderdate

  measures:
    - name: t7d_customers
      expr: COUNT(DISTINCT o_custkey)
      window:
        - order: date
          range: trailing 7 day
          semiadditive: last
$$

Esempio di misura della finestra periodo su periodo

Nell'esempio seguente viene calcolata la crescita delle vendite giornaliere confrontando i ricavi odierni (somma di tutti i prezzi degli ordini) con i ricavi di ieri. Questa metrica identifica le tendenze di vendita giornaliere e mostra la variazione percentuale dei ricavi.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
measures:
  - name: previous_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: trailing 1 day
        semiadditive: last
  - name: current_day_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: current
        semiadditive: last
  - name: day_over_day_growth
    expr: (MEASURE(current_day_sales) - MEASURE(previous_day_sales)) / MEASURE(previous_day_sales) * 100

Per questo esempio, si applica la configurazione seguente:

• Nell'esempio vengono utilizzate due misure finestra: una per calcolare le vendite totali nel giorno precedente e una per il giorno corrente.
• Una terza misura calcola la variazione percentuale (crescita) tra i giorni correnti e precedenti.

Esempio di misura finestra anno su anno usando offset

Il modificatore offset è l'elemento costitutivo per le misure di confronto tra periodi. Definire una copia spostata di una misura di base, quindi comporre i due per esprimere delta, rapporti o tassi di crescita direttamente nella visualizzazione delle metriche.

Nell'esempio seguente viene calcolata la crescita delle vendite dell'anno oltre l'anno confrontando le vendite di ogni mese con lo stesso mese nell'anno precedente. La misura spostata usa offset: -12 month per guardare indietro di 12 mesi lungo il month campo.

version: 1.1
source: main.default.monthly_sales

fields:
  - name: month
    expr: month
  - name: category
    expr: category

measures:
  - name: monthly_sales
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last

  - name: monthly_sales_py
    expr: SUM(sales)
    window:
      - order: month
        range: current
        semiadditive: last
        offset: -12 month

  - name: yoy_growth
    expr: MEASURE(monthly_sales) - MEASURE(monthly_sales_py)

  - name: yoy_growth_pct
    expr: (MEASURE(monthly_sales) - MEASURE(monthly_sales_py))
      / NULLIF(MEASURE(monthly_sales_py), 0)

Per questo esempio, si applica la configurazione seguente:

• monthly_sales è la misura di base, sommando le vendite per il mese corrente.
• monthly_sales_py è la stessa misura spostata indietro di 12 mesi usando offset: -12 month. Per gennaio 2025, restituisce il valore per gennaio 2024.
• yoy_growth e yoy_growth_pct comporre le due misure per esprimere la variazione assoluta e percentuale. L'uso di NULLIF evita errori di divisione per zero quando il valore dell'anno precedente è zero.

Esempio di misura totale cumulativa (in esecuzione)

Nell'esempio seguente vengono calcolati i ricavi cumulativi delle vendite dall'inizio del set di dati fino a ogni data. Questo totale in esecuzione mostra la quantità di ricavi totali generati nel tempo, utile per tenere traccia dello stato di avanzamento verso obiettivi di ricavi annuali o analizzare i modelli di crescita a lungo termine.

version: 1.1
source: samples.tpch.orders

filter: o_orderdate > DATE'1998-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: customer
    expr: o_custkey

measures:
  - name: running_total_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last

Per questo esempio, si applica la configurazione seguente:

• order: date ordina cronologicamente la finestra.
• range: cumulative definisce la finestra come tutti i dati dall'inizio del dataset fino a ciascuna data inclusa.
• semiadditive: last restituisce il valore cumulativo più recente quando date non è incluso nell'GROUP BY della query, anziché sommarlo su tutte le date.

Esempio di misura da inizio periodo a oggi

Nell'esempio seguente vengono calcolati i ricavi delle vendite da inizio anno (YTD). Questa misura mostra i ricavi cumulativi generati dal 1° gennaio di ogni anno fino alla data corrente, reimpostando all'inizio di ogni nuovo anno.

version: 1.1

source: samples.tpch.orders
filter: o_orderdate > DATE'1997-01-01'

fields:
  - name: date
    expr: o_orderdate
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)
measures:
  - name: ytd_sales
    expr: SUM(o_totalprice)
    window:
      - order: date
        range: cumulative
        semiadditive: last
      - order: year
        range: current
        semiadditive: last

Per questo esempio, si applica la configurazione seguente:

• Nell'esempio vengono utilizzate due specifiche della finestra: una per la somma cumulativa sul date campo e un'altra per limitare la somma all'anno current .
• Il year campo limita la somma cumulativa in modo che venga reimpostata all'inizio di ogni nuovo anno.
• I campi month e year formano una gerarchia di date sul campo ordine date: ciascuno è definito nel campo date in base al nome, non sulla colonna sottostante o_orderdate, in modo che le query possano raggruppare questa misura in base a essi. Vedere Raggruppare per un campo gerarchia di date.

Esempio di misura semiadditiva

L'esempio seguente calcola i saldi del conto, che non devono essere sommati tra le date (non è possibile aggiungere il saldo di lunedì al saldo di martedì per ottenere il saldo totale). Al contrario, quando si aggrega tra più giorni, la misura restituisce il saldo più recente. Tuttavia, la misura può comunque essere sommata tra i clienti per mostrare il saldo totale in tutti i conti in un determinato giorno.

version: 1.1

fields:
  - name: date
    expr: date
  - name: customer
    expr: customer_id

measures:
  - name: semiadditive_balance
    expr: SUM(balance)
    window:
      - order: date
        range: current
        semiadditive: last

Per questo esempio, si applica la configurazione seguente:

• order: date ordina cronologicamente la finestra.
• range: current limita la finestra a un singolo giorno senza aggregazioni tra giorni.
• semiadditive: last restituisce il saldo più recente durante l'aggregazione in più giorni.

Interrogare una misura della finestra

È possibile eseguire query su una visualizzazione metrica con una misura della finestra come qualsiasi altra visualizzazione metrica. Una misura di finestra viene calcolata in base al campo order, quindi una query che suddivide i risultati nel tempo deve fare riferimento a quel campo, direttamente oppure tramite un campo di gerarchia delle date definito su di esso. Quando la query non fa riferimento al campo order, la semiadditive parola chiave determina il valore restituito, come descritto in Esempio di misura semiadditive.

L'esempio seguente raggruppa una misura di finestra per state e per un'espressione mensile sul campo order date:

SELECT
   state,
   DATE_TRUNC('month', date),
   MEASURE(t7d_customers) as m
FROM my_metric_view
WHERE date >= DATE'2024-06-01'
GROUP BY ALL

Raggruppare in base a un campo della gerarchia di date

Una gerarchia di date raggruppa il campo a livelli di granularità più elevati, ad esempio alla settimana, al mese o all'anno. Definire ogni livello come un campo sul campo di ordinamento per nome, non sulla colonna di origine sottostante:

fields:
  - name: date
    expr: o_orderdate
  # Date hierarchy: each level is defined on the order field `date`,
  # not on the underlying o_orderdate column.
  - name: month
    expr: DATE_TRUNC('MONTH', date)
  - name: year
    expr: DATE_TRUNC('year', date)

Il raggruppamento di una misura della finestra in base a un livello di gerarchia restituisce la misura in corrispondenza di tale granularità. Supponendo che l'esempio period-to-date venga creato come ytd_metric_view, come nell'esempio di misura period-to-date, la query seguente restituisce il valore YTD alla data dell'ultimo giorno di ciascun mese:

SELECT month, MEASURE(ytd_sales) AS ytd_sales
FROM ytd_metric_view
GROUP BY month
ORDER BY month;

Componibilità

Le visualizzazioni delle metriche sono componibili. È possibile creare nuovi campi e misure che fanno riferimento a quelli esistenti anziché riscrivere la logica da zero. In questo modo si riduce la duplicazione e si semplifica la gestione delle definizioni delle metriche complesse.

La componibilità funziona a due livelli: all'interno di una singola visualizzazione metrica e tra le visualizzazioni delle metriche quando una vista metrica viene usata come origine per un'altra.

La componibilità supporta i modelli di riferimento seguenti:

• Campi precedenti in nuovi campi.
• Campi e misure precedenti nelle nuove misure.
• Campi delle viste metriche utilizzati come origine nei nuovi campi.
• Campi e misure dalle visualizzazioni delle metriche usate come origine nelle nuove misure.

Definire misure con componibilità

measures Nella sezione è possibile fare riferimento a misure dalla vista metrica di origine o dalle misure definite in precedenza nella stessa vista metrica. Questo approccio migliora coerenza, controllabilità e manutenzione del livello semantico.

Esempio: Valore dell'ordine medio (AOV)

Nell'esempio seguente viene definito il valore medio dell'ordine (AOV) usando due misure atomico: total_revenue (somma dei prezzi degli ordini) e order_count (numero di ordini). La avg_order_value misura fa riferimento a entrambe le misure atomiche.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Revenue
  - name: total_revenue
    expr: SUM(o_totalprice)

  # Order Count
  - name: order_count
    expr: COUNT(1)

  # Composed Measure: Average Order Value (AOV)
  - name: avg_order_value
    # Defines AOV as Total Revenue divided by Order Count
    expr: MEASURE(total_revenue) / MEASURE(order_count)

Se la total_revenue definizione cambia (ad esempio, per escludere l'imposta), avg_order_value usa automaticamente la definizione aggiornata.

Componibilità con la logica condizionale

È possibile usare la componibilità per creare rapporti complessi, percentuali condizionali e tassi di crescita senza basarsi sulle funzioni finestra per semplici calcoli di periodi nel corso del periodo.

Esempio: Tasso di evasione

Nell'esempio seguente viene calcolato il tasso di evasione: la percentuale di ordini con stato 'F' (evaso). La misura divide gli ordini evasi per gli ordini totali.

version: 1.1

source: samples.tpch.orders

measures:
  # Total Orders (denominator)
  - name: total_orders
    expr: COUNT(1)

  # Fulfilled Orders (numerator)
  - name: fulfilled_orders
    expr: COUNT(1) FILTER (WHERE o_orderstatus = 'F')

  # Composed Measure: Fulfillment Rate (Ratio)
  - name: fulfillment_rate
    expr: MEASURE(fulfilled_orders) / MEASURE(total_orders)
    format:
      type: percentage

Procedure consigliate per la componibilità

1. Definire prima le misure atomico: stabilire misure fondamentali (SUM, COUNT, AVG) prima di definire misure che vi fanno riferimento.
2. Usare MEASURE() per i riferimenti: usare la MEASURE() funzione quando si fa riferimento a un'altra misura in un oggetto expr. Non ripetere manualmente la logica di aggregazione. Ad esempio, evitare SUM(a) / COUNT(b) se esistono misure per entrambi i valori.
3. Classificare in ordine di priorità la leggibilità: comporre misure usando formule matematiche chiare. Ad esempio, MEASURE(gross_profit) / MEASURE(total_revenue) è più chiaro di una singola espressione SQL complessa.
4. Aggiungere metadati semantici: usare metadati semantici per formattare misure composte (ad esempio, percentuali o valuta) per gli strumenti downstream. Vedere Metadati dell'agente nelle visualizzazioni delle metriche.

Risorse aggiuntive

• Visualizzazioni delle metriche del modello
• Metadati dell'agente nelle visualizzazioni delle metriche
• Materializzazione per le visualizzazioni delle metriche
• Informazioni di riferimento sulla sintassi YAML per la visualizzazione delle metriche