Referenz zur YaML-Syntax der Metrikansicht

Auf dieser Seite wird die vollständige YAML-Grammatik für Metrikansichten erläutert. Metrische Ansichtsdefinitionen folgen der standardmäßigen YAML-Notationssyntax.

Die Mindestversionsanforderungen für laufzeit- und YAML-Spezifikationen für jedes Feature finden Sie unter Verfügbarkeit der metrischen Ansichtsfeatures.

Weitere Informationen zu YAML-Spezifikationen finden Sie in der YAML-Spezifikationsdokumentation 1.2.2 .

YAML-Übersicht

Die YAML-Definition für eine Metrikansicht enthält die folgenden Felder auf oberster Ebene:

Quelle

Das source Feld gibt die Datenquelle für die Metrikansicht an. Sie können eine tabellenähnliche Ressource wie Tabellen, Ansichten und Metrikansichten oder eine SQL-Abfrage als Quelle verwenden. Die Kompositierbarkeit gilt für metrische Ansichten. Wenn Sie eine Metrikansicht als Quelle verwenden, können Sie in der neuen Metrikansicht auf seine Dimensionen und Measures verweisen. Siehe Kompositierbarkeit.

Tabellenähnliche Ressourcenquelle

Verweisen Sie mithilfe des dreiteiligen Namens auf eine tabellenähnliche Ressource:

source: catalog.schema.source_table

SQL-Abfragequelle

Um eine SQL-Abfrage zu verwenden, schreiben Sie den Abfragetext direkt in das YAML:

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

Filter

Ein Filter in der YAML-Definition gilt für alle Abfragen, die auf die Metrikansicht verweisen. Schreiben Sie Filter als boolesche SQL-Ausdrücke.

# 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'

Verknüpfungen

Verknüpfungen in Metrikansichten unterstützen sowohl direkte Verknüpfungen aus einer Faktentabelle als auch Bemaßungstabellen (Sternschema) und Multi-Hop-Verknüpfungen über normalisierte Dimensionstabellen (Schneeflakeschemas). Sie können auch mithilfe einer Anweisung mit einer SELECT SQL-Abfrage verknüpft werden. Siehe Verwenden einer SQL-Abfrage als Quelle.

Jede Verknüpfungsdefinition enthält die folgenden Felder:

Star-Schemabeitritte

In einem Sternschema ist die source die Faktentabelle und wird mit einer oder mehreren Dimensionstabellen mithilfe eines LEFT OUTER JOIN verbunden. Metrikansichten verknüpfen die Fakten- und Dimensionstabellen, die für die spezifische Abfrage erforderlich sind, basierend auf den ausgewählten Spalten.

Angeben von Verknüpfungsspalten mithilfe einer ON Klausel oder einer USING Klausel:

• ON-Klausel: Verwendet einen booleschen Ausdruck, um die Verknüpfungsbedingung zu definieren.
• USING-Klausel: Listet Spalten mit demselben Namen sowohl in der übergeordneten Tabelle als auch in der verknüpften Tabelle auf.

Die Verbindung sollte einer Eins-zu-viele-Beziehung folgen. In Fällen von viele-zu-viele wird die erste übereinstimmende Zeile aus der verbundenen Dimensionstabelle ausgewählt.

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

dimensions:
  - 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)

Snowflake-Schemabeitritte

Ein Schneeflakeschema erweitert ein Sternschema durch Normalisieren von Dimensionstabellen und verbinden sie mit Unterdimensionen. Dadurch wird eine mehrstufige Verknüpfungsstruktur erstellt. Siehe Verfügbarkeit der Metrikansichtsfeatures für Mindestlaufzeitanforderungen.

Um ein Schneeflakeschema zu definieren, schachteln joins Sie in einer übergeordneten Verknüpfungsdefinition:

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

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

Maße

Dimensionen sind Spalten, die zur Abfragezeit in SELECT, WHEREund GROUP BY Klauseln verwendet werden. Jeder Ausdruck muss einen skalaren Wert zurückgeben. Dimensionen können aus den Quelldaten oder früher definierten Dimensionen in der Metrikansicht auf Spalten verweisen.

Jede Dimensiondefinition enthält die folgenden Felder:

Beispiel:

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

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

  # Dimension 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']

Maßnahmen

Measures sind Ausdrücke, die Ergebnisse ohne eine vordefinierte Aggregationsebene erzeugen. Sie müssen mithilfe von Aggregatfunktionen ausgedrückt werden. Verwenden Sie die MEASURE Funktion, um auf ein Measure in einer Abfrage zu verweisen. Measures können auf Basisfelder in den Quelldaten, früher definierten Dimensionen oder früher definierten Measures verweisen.

Jede Measuredefinition enthält die folgenden Felder:

Eine Liste der Aggregatfunktionen finden Sie unter " Aggregatfunktionen ".

Beispiel:

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']

Fenstermaße

Das window Feld definiert fensterierte, kumulierte oder semiadditive Aggregationen für Measures. Ausführliche Informationen zu Fenstermaßen und Anwendungsfällen finden Sie unter Window-Measures.

Jede Fensterspezifikation enthält die folgenden Felder:

Beispiel für Fenstermaß

Im folgenden Beispiel wird eine fortlaufende 7-Tage-Anzahl eindeutiger Kunden berechnet:

version: 1.1
source: samples.tpch.orders

dimensions:
  - 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

Materialisation

Das materialization Feld konfiguriert die automatische Abfragebeschleunigung mithilfe materialisierter Ansichten. Ausführliche Informationen dazu, wie Materialisierung, Anforderungen und bewährte Methoden funktionieren, finden Sie unter Materialization für Metrikansichten.

Das materialization Feld enthält die folgenden Felder auf oberster Ebene:

Jeder Eintrag enthält materialized_views die folgenden Felder:

Materialisierungsbeispiel

Im folgenden Beispiel wird eine Metrikansicht mit mehreren Materialisierungen definiert:

version: 1.1
source: samples.tpch.orders

dimensions:
  - 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

Spaltennamenverweise

Wenn Sie in YAML-Ausdrücken auf Spaltennamen verweisen, die Leerzeichen oder Sonderzeichen enthalten, schließen Sie die betreffenden Spaltennamen in Backticks ein, um die Leer- oder Sonderzeichen zu maskieren. Wenn der Ausdruck mit einem Backtick beginnt und direkt als YAML-Wert verwendet wird, schließen Sie den gesamten Ausdruck in doppelte Anführungszeichen ein. Gültige YAML-Werte dürfen nicht mit einem Backtick beginnen.

Formatierungsbeispiele

In den folgenden Beispielen erfahren Sie, wie Sie YAML in gängigen Szenarien richtig formatieren.

Auf einen Spaltennamen verweisen

In der folgenden Tabelle wird gezeigt, wie Spaltennamen je nach den darin enthaltenen Zeichen formatiert werden.

Verwenden Sie Ausdrücke mit Doppelpunkten

Mehrzeiliger Einzug

Aktualisieren Von YAML auf 1.1

Das Upgrade einer Metrikansicht auf yaML-Spezifikation, Version 1.1, erfordert Sorgfalt, da Kommentare anders behandelt werden als in früheren Versionen.

Arten von Kommentaren

• YAML-Kommentare (#):Inline- oder einzeilige Kommentare, die direkt in der YAML-Datei mit dem Symbol #geschrieben wurden.
• Kommentare im Unity-Katalog: Kommentare, die im Unity-Katalog für die Metrikansicht oder die zugehörigen Spalten (Dimensionen und Measures) gespeichert sind. Diese sind von YAML-Kommentaren getrennt.

Überlegungen zum Upgrade

Wählen Sie den Upgradepfad aus, der der Behandlung von Kommentaren in der Metrikansicht entspricht. Die folgenden Optionen beschreiben die verfügbaren Ansätze und stellen Beispiele bereit.

Option 1: Beibehalten von YAML-Kommentaren mithilfe von Notizbüchern oder dem SQL-Editor

Wenn Ihre Metrikansicht YAML-Kommentare (#) enthält, die Sie beibehalten möchten, führen Sie die folgenden Schritte aus:

1. Verwenden Sie den ALTER VIEW Befehl in einem Notizbuch oder SQL-Editor.
2. Kopieren Sie die ursprüngliche YAML-Definition in den $$..$$ Abschnitt danach AS. Ändern Sie den Wert von version in 1.1.
3. Speichern Sie die Metrikansicht.

ALTER VIEW metric_view_name AS
$$
# The notebook preserves inline comments
version: 1.1
source: samples.tpch.orders
dimensions:
- 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)
$$

Option 2: Beibehalten von Unity-Katalogkommentaren

1. Kopieren Sie alle Unity-Katalogkommentare in die entsprechenden comment Felder in Ihrer YAML-Definition. Ändern Sie den Wert von version in 1.1.
2. Speichern Sie die Metrikansicht.

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

Informationen zum Versionsverlauf der YAML-Spezifikation und mindesten Laufzeitanforderungen für jedes Feature finden Sie unter Verfügbarkeit der metrischen Ansichtsfeatures.