Condividi tramite

Informazioni di riferimento sulla sintassi YAML

Le definizioni di visualizzazione delle metriche seguono la sintassi di notazione YAML standard. Questa pagina illustra come definire una visualizzazione delle metriche.

Per altre informazioni sulle specifiche YAML, vedere la documentazione relativa alla specifica YAML 1.2.2 .

Panoramica di YAML

La definizione YAML per una visualizzazione delle metriche include i campi di primo livello seguenti:

  • version: il valore predefinito è 1.1. Questa è la versione della specifica della visualizzazione delle metriche. Vedere registro delle modifiche delle specifiche di versione.
  • source: dati di origine per la visualizzazione delle metriche. Può trattarsi di un asset simile a una tabella o di una query SQL.
  • joins: facoltativo. Sono supportati i join tra schema a stella e schema a fiocco di neve.
  • filter: facoltativo. Espressione booleana SQL che si applica a tutte le query; equivalente alla WHERE clausola .
  • comment: facoltativo. Descrizione della visualizzazione delle metriche.
  • dimensions: matrice di definizioni di dimensione, inclusi il nome e l'espressione della dimensione.
  • measures: matrice di colonne di espressioni di aggregazione.

Riferimenti ai nomi di colonna

Quando si fa riferimento ai nomi di colonna che contengono spazi o caratteri speciali nelle espressioni YAML, racchiudere il nome della colonna nei backtick per eseguire l'escape dello spazio o del carattere. Se l'espressione inizia con un backtick e viene usata direttamente come valore YAML, racchiudi l'intera espressione tra virgolette doppie. I valori YAML validi non possono iniziare con un backtick.

Esempi di formattazione

Usare gli esempi seguenti per informazioni su come formattare correttamente YAML in scenari comuni.

Fare riferimento a un nome di colonna

Nella tabella seguente viene illustrato come formattare i nomi delle colonne in base ai caratteri che contengono.

Caso Nomi delle colonne sorgente Espressioni di riferimento Note
Nessuno spazio revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 Usare virgolette doppie, virgolette singole o senza virgolette intorno al nome della colonna.
Con spazi First Name expr: "`First Name`" Usare i backtick per gli spazi di escape. Racchiudere l'intera espressione tra virgolette doppie.
Nome della colonna con spazi in un'espressione SQL First Name e Last Name expr: CONCAT(`First Name`, , `Last Name`) Se l'espressione non inizia con gli accenti gravi, le virgolette non sono necessarie.
Le virgolette sono incluse nel nome della colonna di origine "name" expr: '`"name"`' Usare i backtick per eseguire l'escape delle virgolette doppie nel nome della colonna. Racchiudere l'espressione tra virgolette singole nella definizione YAML.

Usare espressioni con due punti

Caso Expression Note
Espressioni con due punti expr: "CASE WHEN Livello cliente = 'Enterprise: Premium' THEN 1 ELSE 0 END" Racchiudere l'intera espressione tra virgolette doppie per un'interpretazione corretta

Annotazioni

YAML interpreta i due punti non virgolettati come separatori di chiave-valore. Usare sempre virgolette doppie per le espressioni che includono i due punti.

Indentazione multilinea

Caso Expression Note
Indentazione multilinea expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Rientrare l'espressione nella prima riga

Annotazioni

Usare il | blocco scalare dopo expr: per le espressioni su più righe. Tutte le righe devono essere rientrate almeno di due spazi oltre il delimitatore expr per una corretta analisi.

Definire una dimensione

Nell'esempio seguente viene illustrato come definire le dimensioni:

dimensions:

  # Column name
  - name: Order date
    expr: o_orderdate

  # SQL expression
  - name: Order month
    expr: DATE_TRUNC('MONTH', `Order date`)

  # Referring to a column with a space in the name
  - name: Month of order
    expr: `Order month`

  # Multi-line expression
  - name: Order status
    expr: CASE
            WHEN o_orderstatus = 'O' THEN 'Open'
            WHEN o_orderstatus = 'P' THEN 'Processing'
            WHEN o_orderstatus = 'F' THEN 'Fulfilled'
          END

Definire una misura

Nell'esempio seguente viene illustrato come definire le misure:

measures:

  # Basic aggregation
  - name: Total revenue
    expr: SUM(o_totalprice)

  # Basic aggregation with ratio
  - name: Total revenue per customer
    expr: SUM(`Total revenue`) / COUNT(DISTINCT o_custkey)

  # Measure-level filter
  - name: Total revenue for open orders
    expr: COUNT(o_totalprice) FILTER (WHERE o_orderstatus='O')

  # Measure-level filter with multiple aggregate functions
  # filter needs to be specified for each aggregate function in the expression
  - name: Total revenue per customer for open orders
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus='O')/COUNT(DISTINCT o_custkey) FILTER (WHERE o_orderstatus='O')

Mappatura dei nomi delle colonne in CREATE VIEW con YAML

Quando si crea una visualizzazione delle metriche usando CREATE VIEW con column_list, il sistema esegue il mapping delle colonne definite da YAML (misure e dimensioni) ai column_list per posizione, non in base al nome.

Di seguito è riportato il comportamento SQL standard, come illustrato nell'esempio seguente:

CREATE VIEW v (col1, col2) AS SELECT a, b FROM table;

In questo esempio, a viene mappato a col1, e b viene mappato a col2, indipendentemente dai loro nomi originali.

Aggiornare YAML alla versione 1.1

L'aggiornamento di una visualizzazione delle metriche alla specifica YAML versione 1.1 richiede attenzione, perché i commenti vengono gestiti in modo diverso rispetto alle versioni precedenti.

Tipi di commenti

  • Commenti YAML (#): commenti inline o a riga singola scritti direttamente nel file YAML usando il simbolo #.
  • Commenti del catalogo Unity: commenti archiviati in Unity Catalog per la visualizzazione delle metriche o le relative colonne (dimensioni e misure). Questi elementi sono separati dai commenti YAML.

Considerazioni sull'aggiornamento

Scegliere il percorso di aggiornamento che corrisponde alla modalità di gestione dei commenti nella visualizzazione delle metriche. Le opzioni seguenti descrivono gli approcci disponibili e forniscono esempi.

Opzione 1: Mantenere i commenti YAML usando notebook o l'editor SQL

Se la visualizzazione delle metriche contiene commenti YAML (#) da mantenere, seguire questa procedura:

  1. Usare il ALTER VIEW comando in un notebook o in un editor SQL.

  2. Copiare la definizione YAML originale nella sezione $$..$$ dopo AS. Modificare il valore della versione in 1.1.

  3. Salvare la visualizzazione delle metriche.

ALTER VIEW metric_view_name AS
$$
# Inline comments are preserved in the notebook
version: 1.1
source: samples.tpch.orders
dimensions:
- name: order_date # Inline comments are preserved in the notebook
  expr: o_orderdate
measures:
# Commented out definition is preserved
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Avvertimento

L'esecuzione ALTER VIEW rimuove i commenti del catalogo Unity, a meno che non siano inclusi in modo esplicito nei comment campi della definizione YAML. Per mantenere i commenti visualizzati nel catalogo unity, vedere l'opzione 2.

Opzione 2: Mantenere i commenti del catalogo Unity

Annotazioni

Le indicazioni seguenti si applicano solo quando si usa il ALTER VIEW comando in un notebook o in un editor SQL. Se si aggiorna la visualizzazione delle metriche alla versione 1.1 usando l'interfaccia utente dell'editor YAML, i commenti del catalogo Unity verranno mantenuti automaticamente.

  1. Copiare tutti i commenti del catalogo Unity nei campi appropriati comment nella definizione YAML. Modificare il valore della versione in 1.1.

  2. Salvare la visualizzazione delle metriche.

ALTER VIEW metric_view_name AS
$$
version: 1.1
source: samples.tpch.orders
comment: "Metric view of order (Updated comment)"


dimensions:
- name: order_date
  expr: o_orderdate
  comment: "Date of order - Copied from Unity Catalog"


measures:
- name: total_revenue
  expr: SUM(o_totalprice)
  comment: "Total revenue"
$$

Registro delle modifiche delle specifiche della versione

Versione 1.1 (richiede Databricks Runtime 17.2 o versione successiva)

Versione 0.1 (richiede Databricks Runtime da 16.4 a 17.1)

  • Versione iniziale della specifica YAML della visualizzazione delle metriche.
  • Last updated on