Informazioni di riferimento sulla sintassi YAML per la visualizzazione delle metriche

Le definizioni di visualizzazione delle metriche usano la sintassi YAML standard per dichiarare origine, join, campi, misure, filtri, misure finestra e materializzazione. Le sezioni seguenti descrivono la grammatica completa per ognuna.

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

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

Modificare YAML nell'editor di visualizzazione delle metriche

È possibile scrivere e modificare il codice YAML descritto in questa pagina direttamente nell'editor di visualizzazione delle metriche. In Esplora cataloghi aprire una visualizzazione delle metriche e fare clic sul <> pulsante per modificare la definizione. Per generare YAML da una descrizione del linguaggio naturale, aprire invece Genie Code dall'editor. Per la procedura dettagliata dell'editor completo, vedere Creare una visualizzazione delle metriche.

Campi YAML di primo livello

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

Fonte

Il source campo specifica l'origine dati per la visualizzazione metrica. Le origini supportate includono tabelle, viste, viste delle metriche e query SQL. La componibilità si applica tra le visualizzazioni delle metriche. Quando si usa una visualizzazione metrica come origine, è possibile fare riferimento ai relativi campi e misure nella nuova visualizzazione delle metriche. Vedere Componibilità.

Origine di asset simili a tabelle

Fare riferimento a un asset simile a una tabella usando il nome in tre parti:

source: catalog.schema.source_table

Origine query SQL

Per usare una query SQL, scrivere il testo della query direttamente in YAML:

source: SELECT * FROM samples.tpch.orders o
  LEFT JOIN samples.tpch.customer c
  ON o.o_custkey = c.c_custkey

Parametri

Il parameters blocco definisce valori denominati che i chiamanti passano quando eseguono query sulla vista metrica come funzione con valori di tabella. Per quando e come usare i parametri, inclusa l'esecuzione di query su una vista metrica con parametri, vedere Usare i parametri con le visualizzazioni delle metriche.

Ogni definizione di parametro include i campi seguenti:

L'esempio seguente definisce un discount parametro e vi fa riferimento in un'espressione di misura:

version: 1.1
source: main.default.sales

parameters:
  - name: discount
    data_type: double
    default: 0

fields:
  - name: product
    expr: product

measures:
  - name: discountedSales
    expr: SUM((1 - discount) * amount)

Filter

Un filtro nella definizione YAML si applica a tutte le query che fanno riferimento alla visualizzazione metrica. Scrivere filtri come espressioni booleane SQL.

# Single condition filter
filter: o_orderdate > '2024-01-01'

# Multiple conditions with AND
filter: o_orderdate > '2024-01-01' AND o_orderstatus = 'F'

# Multiple conditions with OR
filter: o_orderpriority = '1-URGENT' OR o_orderpriority = '2-HIGH'

# Complex filter with IN clause
filter: o_orderstatus IN ('F', 'P') AND o_orderdate >= '2024-01-01'

# Filter with NOT
filter: o_orderstatus != 'O' AND o_totalprice > 1000.00

# Filter with LIKE pattern matching
filter: o_comment LIKE '%express%' AND o_orderdate > '2024-01-01'

Joins

I join nelle viste delle metriche supportano sia i join diretti da una tabella dei fatti a tabelle delle dimensioni (schema a stella) che i join multi-hop tra tabelle delle dimensioni normalizzate (schemi a fiocco di neve). È anche possibile creare un join a una query SQL usando un'istruzione SELECT . Vedere Usare una query SQL come origine.

Ogni definizione di join include i campi seguenti:

Join dello schema a stella

In uno schema a stella, source è la tabella dei fatti e si collega a una o più tabelle delle dimensioni utilizzando un LEFT OUTER JOIN. Le viste delle metriche si uniscono alle tabelle dei fatti e delle dimensioni necessarie per la query specifica, in base alle colonne selezionate.

Specificare le colonne join usando una ON clausola o una USING clausola :

• ON clausola: usa un'espressione booleana per definire la condizione di join.
• USING clausola: elenca le colonne con lo stesso nome sia nella tabella padre che nella tabella unita in join.

Il join deve basarsi su una relazione da molti a uno. In casi di molti a molti, viene selezionata la prima riga corrispondente dalla tabella dimensionale unita tramite join.

version: 1.1
source: samples.tpch.lineitem

joins:
  - name: orders
    source: samples.tpch.orders
    on: source.l_orderkey = orders.o_orderkey

  - name: part
    source: samples.tpch.part
    on: source.l_partkey = part.p_partkey

fields:
  - name: Order Status
    expr: orders.o_orderstatus

  - name: Part Name
    expr: part.p_name

measures:
  - name: Total Revenue
    expr: SUM(l_extendedprice * (1 - l_discount))

  - name: Line Item Count
    expr: COUNT(1)

Join dello schema Snowflake

Uno schema snowflake estende uno schema star normalizzando le tabelle delle dimensioni e collegandole alle sottodimensioni. Verrà creata una struttura di unione a più livelli. Per i requisiti minimi di runtime, vedere Disponibilità delle funzionalità di visualizzazione delle metriche .

Per definire uno schema snowflake, annidare joins all'interno di una definizione di join padre:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    'on': o_custkey = c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        'on': c_nationkey = n_nationkey

fields:
  - name: customer_nation
    expr: customer.nation.n_name

Join uno-a-molti

Il cardinality campo imposta la relazione tra l'origine e una tabella unita in join. Il valore predefinito, many_to_one, considera la tabella unita come ricerca di dimensioni. Impostare cardinality: one_to_many per considerare la tabella unita in join come origine dei fatti che il motore aggrega in modo indipendente in base alla granularità di origine, che consente a una singola riga di origine di corrispondere a più righe nella tabella unita in join. I join uno-a-molti richiedono Databricks Runtime 18.1 o superiore e la specifica YAML 1.1. Vedere Disponibilità delle funzionalità di visualizzazione delle metriche.

Le regole seguenti si applicano ai join uno-a-molti:

• Una colonna uno-a-molti non può essere usata in una fields definizione, perché un campo deve essere risolto in un singolo valore per ogni riga di origine.
• Una singola funzione di aggregazione deve fare riferimento alle colonne di un'origine. È possibile applicare aritmetica tra i risultati di aggregazioni separate, ad esempio count(orders.order_id) / count(*).
• Anche tutti i discendenti di un join uno-a-molti devono essere one_to_many. I join di pari livello superiore possono combinare cardinalità.
• Fare riferimento a una colonna in un join annidato con il relativo punto-percorso completo tramite i nomi di join, ad esempio orders.order_items.item_id.

L'esempio seguente viene unito orders a un'origine customers con in cardinality: one_to_many modo che le misure degli ordini si aggregano senza duplicare le righe del cliente:

version: 1.1
source: main.sales.customers

joins:
  - name: orders
    source: main.sales.orders
    on: orders.customer_id = source.customer_id
    cardinality: one_to_many

fields:
  - name: customer_name
    expr: customer_name

measures:
  - name: customer_count
    expr: count(*)
  - name: order_count
    expr: count(orders.order_id)
  - name: total_order_revenue
    expr: sum(orders.amount)

Per informazioni concettuali ed esempi di join annidati e di pari livello, vedere Cardinalità di join.

Ottimizzare i join con rely

Usare il rely campo in un join per dichiarare garanzie sulla relazione usata dall'analizzatore di query durante la pianificazione delle query. Queste garanzie consentono al motore di pianificare le query in modo più efficiente e ridurre i dati analizzati, soprattutto quando si fa riferimento ai campi della tabella unita in filtri.

La rely mappa supporta i campi seguenti:

Nell'esempio seguente viene abilitato at_most_one_match un join molti-a-uno da orders a customer. Le query che filtrano o raggruppano in base agli attributi dei clienti traggono il massimo vantaggio:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    rely:
      at_most_one_match: true

fields:
  - name: Customer name
    expr: customer.c_name
  - name: Customer market segment
    expr: customer.c_mktsegment

measures:
  - name: Total revenue
    expr: SUM(o_totalprice)

Campi

I campi sono colonne di visualizzazione delle metriche usate nelle SELECTclausole , WHEREe GROUP BY in fase di query. Ogni espressione deve restituire un valore scalare. I campi possono fare riferimento a colonne dai dati di origine o dai campi definiti in precedenza nella visualizzazione metrica.

Un campo può essere:

• Colonna categorica o di raggruppamento, ad esempio un'area, uno stato o un reparto.
• Colonna numerica non raggruppata, ad esempio età, prezzo o quantità. I campi numerici possono essere aggregati in fase di query usando funzioni SQL come SUM o AVG.

Ogni definizione di campo include le proprietà seguenti:

Example:

fields:
  # Basic field
  - name: order_date
    expr: o_orderdate
    comment: 'Date the order was placed'
    display_name: 'Order Date'

  # Field with SQL expression
  - name: order_month
    expr: DATE_TRUNC('MONTH', o_orderdate)
    display_name: 'Order Month'

  # Field with synonyms
  - name: order_status
    expr: CASE
      WHEN o_orderstatus = 'O' THEN 'Open'
      WHEN o_orderstatus = 'P' THEN 'Processing'
      WHEN o_orderstatus = 'F' THEN 'Fulfilled'
      END
    display_name: 'Order Status'
    synonyms: ['status', 'fulfillment status']

Misure

Le misure sono espressioni che producono risultati senza un livello di aggregazione predeterminato. Devono essere espressi usando funzioni di aggregazione. Per fare riferimento a una misura in una query, usa MEASURE. Le misure possono fare riferimento a colonne di base nei dati di origine, nei campi definiti in precedenza o in misure definite in precedenza.

Ogni definizione di misura include i campi seguenti:

Vedere Funzioni di aggregazione per un elenco di funzioni di aggregazione.

Example:

measures:
  # Simple count measure
  - name: order_count
    expr: COUNT(1)
    display_name: 'Order Count'

  # Sum aggregation measure with synonyms
  - name: total_revenue
    expr: SUM(o_totalprice)
    comment: 'Gross revenue from all orders'
    display_name: 'Total Revenue'
    synonyms: ['revenue', 'total sales']

  # Distinct count measure
  - name: unique_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: 'Unique Customers'

  # Calculated measure combining multiple aggregations
  - name: avg_order_value
    expr: SUM(o_totalprice) / COUNT(DISTINCT o_orderkey)
    display_name: 'Avg Order Value'
    synonyms: ['AOV', 'average order']

  # Filtered measure with WHERE condition
  - name: open_order_revenue
    expr: SUM(o_totalprice) FILTER (WHERE o_orderstatus = 'O')
    display_name: 'Open Order Revenue'
    synonyms: ['backlog', 'outstanding revenue']

Importa in blocco campi e misure con caratteri jolly

Si applica a: Databricks Runtime 18.2 e versioni successive con la specifica YAML 1.1

In una fields definizione o measures è possibile usare un carattere jolly (*) nel expr campo per importare tutte le colonne dall'origine o da una tabella unita senza elencarne ognuna. Ciò è utile quando si vuole che una visualizzazione metrica esponga ogni colonna da un asset upstream, simile a SELECT * in una visualizzazione standard. Azure Databricks espande il carattere jolly alle colonne concrete quando si crea o si sostituisce la vista metrica e deriva ogni nome di colonna dal nome della colonna di origine.

Analogamente alle definizioni di colonna esplicite, le espressioni con caratteri jolly vengono espanse quando si crea la visualizzazione delle metriche. Per recuperare le colonne aggiunte all'origine in un secondo momento, ricreare la visualizzazione delle metriche con CREATE OR REPLACE o ALTER.

I caratteri jolly supportano i formati seguenti:

Le regole seguenti si applicano alle espressioni con caratteri jolly:

• Omettere il name campo. Azure Databricks deriva i nomi di colonna dall'origine, pertanto name non è consentito in un'espressione con caratteri jolly.
• I metadati semantici non sono consentiti in un'espressione con caratteri jolly. Non impostare comment, display_name, formato synonyms su un carattere jolly. Per aggiungere metadati a una colonna specifica, escluderlo dal carattere jolly con EXCEPT e definirlo in modo esplicito.
• In una measures definizione, un carattere jolly importa le misure solo da un'origine vista metrica. Le tabelle di base non dispongono di misure, pertanto un carattere jolly si espande fino a nessuna misura quando l'origine è una tabella di base.
• Non è possibile fare riferimento a una colonna importata con caratteri jolly in base al nome derivato in un'espressione o fields successivameasures. Fare riferimento alla colonna di origine con il percorso completo.

Risolvere i conflitti di nomi

Quando si importano colonne da più di un'origine con un carattere jolly, le colonne che condividono un nome (ad esempio id o date) si scontrano e generano un errore quando si salva la definizione. Per risolvere un conflitto, escludere la colonna da ogni carattere jolly con EXCEPT, quindi definirla in modo esplicito con un nome univoco:

fields:
  - expr: source.* EXCEPT (id)
  - expr: customer.* EXCEPT (id)
  - name: source_id
    expr: source.id
  - name: customer_id
    expr: customer.id

Esempio di caratteri jolly

La definizione seguente importa tutte le colonne dall'origine e da una tabella unita a join, esclude due colonne e definisce una colonna in modo esplicito per aggiungere metadati:

version: 1.1
source: samples.tpch.orders

joins:
  - name: customer
    source: samples.tpch.customer
    on: source.o_custkey = customer.c_custkey
    joins:
      - name: nation
        source: samples.tpch.nation
        on: customer.c_nationkey = nation.n_nationkey

fields:
  # Import all columns from the source
  - expr: source.*

  # Import all columns from a joined table, excluding two
  - expr: customer.nation.* EXCEPT (n_name, n_comment)

  # Define a specific column explicitly to add metadata
  - name: nation_name
    expr: customer.nation.n_name
    comment: "Customer's nation"
    display_name: 'Nation Name'

Misure della finestra

Il window campo definisce aggregazioni finestrate, cumulative o semiadditive per le misure. Per informazioni dettagliate sulle misure finestra e sui casi d'uso, vedere Misure finestra.

Ogni specifica della finestra include i campi seguenti:

(1) Il campo a cui si fa riferimento deve essere deterministico. Espressioni non deterministiche, ad rand()esempio , uuid()o current_timestamp() producono un ordinamento imprevedibile delle finestre e possono causare risultati di aggregazione non corretti.

Valori di range supportati

• current: righe in cui il valore di ordinamento della finestra è uguale al valore della riga di ancoraggio.
• cumulative: tutte le righe in cui il valore di ordinamento della finestra è minore o uguale al valore della riga di ancoraggio.
• trailing <value> <unit> [inclusive | exclusive]: righe dalla riga di ancoraggio che passano all'indietro in base alle unità di tempo specificate, ad esempio trailing 7 day. Il modificatore o inclusive facoltativo exclusive richiede Databricks Runtime 18.1 e la specifica YAML versione 1.1 o successiva e controlla se la riga di ancoraggio è inclusa nella finestra. Il valore predefinito è exclusive. Vedere Includere o escludere la riga di ancoraggio.
• leading <value> <unit> [inclusive | exclusive]: righe dalla riga di ancoraggio in avanti in base alle unità di tempo specificate, ad esempio leading 3 month. Il modificatore o inclusive facoltativo exclusive richiede Databricks Runtime 18.1 e la specifica YAML versione 1.1 o successiva e controlla se la riga di ancoraggio è inclusa nella finestra. Il valore predefinito è exclusive. Vedere Includere o escludere la riga di ancoraggio.
• all: tutte le righe indipendentemente dal valore di ordinamento della finestra.

Esempio di misura finestra

L'esempio seguente calcola un conteggio di 7 giorni di clienti univoci:

version: 1.1
source: samples.tpch.orders

fields:
  - name: order_date
    expr: o_orderdate

measures:
  - name: rolling_7day_customers
    expr: COUNT(DISTINCT o_custkey)
    display_name: '7-Day Rolling Customers'
    window:
      - order: order_date
        range: trailing 7 day
        semiadditive: last

Materializzazione

Il materialization campo configura l'accelerazione automatica delle query usando viste materializzate. Per informazioni dettagliate sul funzionamento della materializzazione, sui requisiti e sulle procedure consigliate, vedere Materializzazione per le visualizzazioni delle metriche.

Il materialization campo include i campi di primo livello seguenti:

Ogni voce in materialized_views include i campi seguenti:

Esempio di materializzazione

L'esempio seguente definisce una visualizzazione delle metriche con più materializzazioni:

version: 1.1
source: samples.tpch.orders

fields:
  - name: order_date
    expr: o_orderdate
  - name: order_status
    expr: o_orderstatus

measures:
  - name: total_revenue
    expr: SUM(o_totalprice)
  - name: order_count
    expr: COUNT(1)

materialization:
  schedule: every 6 hours
  mode: relaxed
  materialized_views:
    - name: baseline
      type: unaggregated

    - name: daily_status_metrics
      type: aggregated
      dimensions:
        - order_date
        - order_status
      measures:
        - total_revenue
        - order_count
      cluster_by:
        cols:
          - order_date
          - order_status
      partition_by:
        - order_date

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

Negli esempi seguenti viene illustrato come formattare i riferimenti alle colonne in base ai caratteri che contengono.

Nessuno spazio

Colonna di origine: revenue

expr: "revenue"
expr: 'revenue'
expr: revenue

Usare virgolette doppie, virgolette singole o senza virgolette intorno al nome della colonna.

Nome colonna con spazi

Colonna di origine: `First Name`

expr: '`First Name`'

Usare i backtick per gli spazi di escape. Racchiudere l'intera espressione tra virgolette doppie.

Nomi di colonna con spazi in un'espressione SQL

Colonne di origine: `First Name`, `Last Name`

expr: CONCAT(`First Name`, ' ', `Last Name`)

Se l'espressione non inizia con un backtick, le virgolette doppie non sono obbligatorie.

Nome di colonna contenente virgolette

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.

Espressioni con due punti

expr: "CASE WHEN `Customer Tier` = 'Enterprise: Premium' THEN 1 ELSE 0 END"

Espressioni a più righe

expr: |
  CASE WHEN
    revenue > 100 THEN 'High'
  ELSE 'Low'
  END

Eseguire l'aggiornamento a YAML 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.
• Commenti del catalogo Unity: commenti archiviati in Unity Catalog per la visualizzazione delle metriche o le relative colonne. Questi elementi sono separati dai commenti YAML.

Considerazioni sull'aggiornamento

Selezionare il percorso di aggiornamento corrispondente alla modalità di gestione dei commenti nella visualizzazione delle metriche.

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 di version in 1.1.
3. Salvare la visualizzazione delle metriche.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
fields:
- name: order_date # The notebook preserves inline comments
  expr: o_orderdate
measures:
# The notebook preserves commented out definitions
# - name: total_orders
#   expr: COUNT(o_orderid)
- name: total_revenue
  expr: SUM(o_totalprice)
$$

Opzione 2: Mantenere i commenti del catalogo Unity

1. Copiare tutti i commenti del catalogo Unity nei campi appropriati comment nella definizione YAML. Modificare il valore di version 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)"

fields:
- 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"
$$

Per la cronologia delle versioni delle specifiche YAML e i requisiti minimi di runtime per ogni funzionalità, vedere Disponibilità delle funzionalità di visualizzazione delle metriche.