YAML-Syntaxreferenz

Metrische Ansichtsdefinitionen folgen der standardmäßigen YAML-Notationssyntax. Auf dieser Seite wird erläutert, wie Sie eine Metrikansicht definieren.

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:

• version: Standardmäßig auf 1.1. Dies ist die Version der Spezifikation für die Metrikansicht. Siehe Änderungsprotokoll zur Versionsspezifikation.
• source: Die Quelldaten für die Metrikansicht. Dies kann ein tabellenähnliches Objekt oder eine SQL-Abfrage sein.
• joins: Optional. Sternschema- und Schneeflakeschemabeitritte werden unterstützt.
• filter: Optional. Ein boolescher SQL-Ausdruck, der für alle Abfragen gilt; entspricht der WHERE Klausel.
• comment: Optional. Beschreibung der Metrikansicht.
• dimensions: Ein Array von Dimensionsdefinitionen, einschließlich des Dimensionsnamens und des Ausdrucks.
• measures: Ein Array von aggregieren Ausdruck Spalten.

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

Definieren einer Dimension

Im folgenden Beispiel wird veranschaulicht, wie Dimensionen definiert werden:

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

Definiere eine Kennzahl

Im folgenden Beispiel wird veranschaulicht, wie Measures definiert werden:

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

Spaltennamenszuordnung in CREATE VIEW YAML

Wenn Sie CREATE VIEW mit column_list verwenden, um eine Metrikansicht zu erstellen, ordnet das System YAML-definierte Spalten (Measures und Dimensionen) column_list nach Position und nicht nach Name zu.

Dies folgt dem standardmäßigen SQL-Verhalten, wie im folgenden Beispiel gezeigt:

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

In diesem Beispiel wird acol1 zugeordnet und b wird col2 zugeordnet, unabhängig von ihren ursprünglichen Namen.

Aktualisieren Sie 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 $$..$$ nach AS. Ändern Sie den Wert der Version in 1.1.

3. Speichern Sie die Metrikansicht.

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

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

Änderungsprotokoll zur Versionsspezifikation

Version 1.1 (erfordert Databricks Runtime 17.2 oder höher)

• Hinzugefügt:
  • Unterstützung für semantische Metadatenfunktionen. Siehe Verwenden semantischer Metadaten in Metrikansichten.
  • Unterstützung für ein optionales YAML-Feld comment zur Beschreibung der Ansicht der Metriken, Dimensionen oder Messgrößen.

Version 0.1 (erfordert Databricks Runtime 16.4 bis 17.1)

• Erste Veröffentlichung der YaML-Spezifikation der Metrikansicht.