Freigeben über

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.

Anfrage Name(n) der Quellspalten Referenzausdrücke(n) Hinweise
Keine Leerzeichen revenue expr: "revenue"
expr: 'revenue'
expr: revenue		 Verwenden Sie doppelte Anführungszeichen, einfache Anführungszeichen oder keine Anführungszeichen um den Spaltennamen.
Mit Leerzeichen First Name expr: "`First Name`" Verwenden Sie Backticks, um Leerzeichen zu maskieren. Schließen Sie den gesamten Ausdruck in doppelte Anführungszeichen ein.
Spaltenname mit Leerzeichen in einem SQL-Ausdruck First Name und Last Name expr: CONCAT(`First Name`, , `Last Name`) Wenn der Ausdruck nicht mit Backticks beginnt, sind keine doppelten Anführungszeichen erforderlich.
Der Name der Quellspalte enthält Anführungszeichen. "name" expr: '`"name"`' Maskieren Sie die doppelten Anführungszeichen im Spaltennamen mit Backticks. Schließen Sie diesen Ausdruck in einfache Anführungszeichen in die YAML-Definition ein.

Verwenden Sie Ausdrücke mit Doppelpunkten

Anfrage Ausdruck Hinweise
Ausdrücke mit Doppelpunkten expr: "CASE WHEN Kundenebene = 'Enterprise: Premium' THEN 1 ELSE 0 END" Umschließen des gesamten Ausdrucks in doppelte Anführungszeichen zur korrekten Interpretation

Hinweis

YAML interpretiert nicht in Anführungszeichen stehende Doppelpunkte als Trennzeichen zwischen Schlüssel und Wert. Schließen Sie Ausdrücke, die Doppelpunkte enthalten, deshalb immer in doppelte Anführungszeichen ein.

Mehrzeiliger Einzug

Anfrage Ausdruck Hinweise
Mehrzeiliger Einzug expr: \|
CASE WHEN
revenue > 100 THEN 'High'
ELSE 'Low'
END		 Rücken Sie den Ausdruck unter der ersten Zeile ein

Hinweis

Verwenden Sie den | Blockskalierer nach expr: für mehrzeilige Ausdrücke. Für eine korrekte Analyse müssen alle Zeilen einen Einzug von mindestens zwei Leerzeichen über den Schlüssel expr hinaus aufweisen.

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

Warnung

Beim Ausführen ALTER VIEW werden Unity-Katalogkommentare entfernt, es sei denn, sie werden explizit in die comment Felder der YAML-Definition eingeschlossen. Wenn Sie Kommentare beibehalten möchten, die im Unity-Katalog angezeigt werden, lesen Sie Option 2.

Option 2: Beibehalten von Unity-Katalogkommentaren

Hinweis

Die folgenden Anleitungen gelten nur, wenn Sie den ALTER VIEW Befehl in einem Notizbuch oder SQL-Editor verwenden. Wenn Sie Ihre Metrikansicht mithilfe der YAML-Editor-Benutzeroberfläche auf Version 1.1 aktualisieren, werden Ihre Unity-Katalogkommentare automatisch beibehalten.

  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)

Version 0.1 (erfordert Databricks Runtime 16.4 bis 17.1)

  • Erste Veröffentlichung der YaML-Spezifikation der Metrikansicht.
  • Last updated on