Referenz zur YaML-Syntax der Metrikansicht

Metrische Ansichtsdefinitionen verwenden die standardmäßige YAML-Syntax, um die Quelle, Verknüpfungen, Felder, Measures, Filter, Fenstermaße und Materialisierung zu deklarieren. In den folgenden Abschnitten wird die vollständige Grammatik für die einzelnen Abschnitte dokumentiert.

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 .

Bearbeiten von YAML im metrischen Ansichts-Editor

Sie können das auf dieser Seite beschriebene YAML direkt im metrischen Ansichts-Editor schreiben und bearbeiten. Öffnen Sie im Katalog-Explorer eine Metrikansicht, und klicken Sie auf die <> Schaltfläche, um die Definition zu bearbeiten. Um YAML stattdessen aus einer Beschreibung natürlicher Sprache zu generieren, öffnen Sie Genie Code aus dem Editor. Eine exemplarische Vorgehensweise für den vollständigen Editor finden Sie unter Erstellen einer Metrikansicht.

YaML-Felder auf oberster Ebene

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

Feld Typ Description
version String Required. Die Version der YAML-Spezifikation der Metrikansicht, die von der Definition verwendet wird, z 1.1. B. . Dies ist die Version des Spezifikationsformats, nicht eine Revisionsnummer, die Sie Ihrer eigenen Definition zuweisen. Verwenden Sie eine der unterstützten Spezifikationsversionen. Siehe YAML-Spezifikationsversionen.
comment String Dies ist optional. Beschreibung der Metrikansicht.
source String Required. Die Quelldaten für die Metrikansicht. Dabei kann es sich um ein beliebiges tabellenähnliches Unity-Katalogobjekt handeln, einschließlich einer Metrikansicht oder einer SQL-Abfrage. Siehe Quelle.
parameters Array Dies ist optional. Benannte Werte, die Aufrufer übergeben, wenn sie die Metrikansicht als Tabellenwertfunktion abfragen. Siehe Parameter.
filter String Dies ist optional. Ein boolescher SQL-Ausdruck, der für alle Abfragen gilt. Siehe Filter.
joins Array Dies ist optional. Sternschema- und Schneeflakeschema-Verknüpfungen. Siehe Verknüpfungen.
fields Array Konditional. Felddefinitionen, einschließlich Name, Ausdruck und optionaler semantischer Metadaten. Erforderlich, wenn keine measures angegeben ist. Siehe Felder. Das dimensions Schlüsselwort wird als Synonym für Abwärtskompatibilität akzeptiert.
measures Array Konditional. Measuredefinitionen, einschließlich Name, Aggregatausdruck und optionaler semantischer Metadaten. Erforderlich, wenn keine fields angegeben ist. Siehe Measures.
materialization Object Dies ist optional. Konfiguration zum Beschleunigen von Abfragen mit materialisierten Ansichten. Enthält Aktualisierungszeitplan- und materialisierte Ansichtsdefinitionen. Siehe Materialisierung.

Source

Das source Feld gibt die Datenquelle für die Metrikansicht an. Zu den unterstützten Quellen gehören Tabellen, Ansichten, Metrikansichten und SQL-Abfragen. Die Kompositierbarkeit gilt für metrische Ansichten. Wenn Sie eine Metrikansicht als Quelle verwenden, können Sie in der neuen Metrikansicht auf die zugehörigen Felder und Kennzahlen 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

Note

Wenn Sie eine SQL-Abfrage als Quelle mit einer JOIN Klausel verwenden, legen Sie Primär- und Fremdschlüsseleinschränkungen für zugrunde liegende Tabellen fest, und verwenden Sie die RELY Option für eine optimale Abfrageleistung. Weitere Informationen finden Sie unter Deklarieren von Primärschlüsseln, Fremdschlüsseln und eindeutigen Einschränkungen undAbfrageoptimierung mithilfe von Primärschlüsseln und eindeutigen Einschränkungen.

Parameter

Der parameters Block definiert benannte Werte, die Aufrufer übergeben, wenn sie die Metrikansicht als Tabellenwertfunktion abfragen. Wann und wie Parameter verwendet werden, einschließlich Abfragen einer parametrisierten Metrikansicht, finden Sie unter Verwenden von Parametern mit Metrikansichten.

Jede Parameterdefinition enthält die folgenden Felder:

Feld Typ Description
name String Required. Der Parametername. Verweisen Sie auf den Parameter anhand dieses Namens in Feld- und Measureausdrücken, und übergeben Sie ihn als benanntes Argument, wenn Sie die Metrikansicht abfragen.
data_type String Required. Der SQL-Datentyp des Parameters, z double. B. , , int, stringoder date.
default Variiert Dies ist optional. Der Wert, der verwendet wird, wenn ein Aufrufer den Parameter nicht übergibt. Der Standardwert muss umwandlungsfähig data_typesein, und er kann nicht auf einen anderen Parameter verweisen oder eine Unterabfrage enthalten. Wenn Sie einen Standardwert für einen Parameter festlegen, muss jeder darauf folgende Parameter auch über einen Standardwert verfügen.

Im folgenden Beispiel wird ein discount Parameter definiert und in einem Measureausdruck darauf verwiesen:

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

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.

Note

Verknüpfte Tabellen können keine Spalten des Typs MAP enthalten. Informationen zum Entpacken von Werten aus Spalten des Typs MAP finden Sie unter Geschachtelte Elemente aus einer Karte oder einem Array entpacken.

Jede Verknüpfungsdefinition enthält die folgenden Felder:

Feld Typ Description
name String Required. Alias für die verknüpfte Tabelle oder SQL-Abfrage. Verwenden Sie diesen Alias beim Verweisen auf Spalten aus der verknüpften Tabelle in Feldern oder Measures.
source String Required. Dreiteiliger Name der zu verbindenden Tabelle. Kann auch eine SQL-Abfrage sein.
on String Konditional. Boolescher Ausdruck, der die Verknüpfungsbedingung definiert. Erforderlich, wenn using nicht angegeben wird.
using Array Konditional. Liste der Spaltennamen, die sowohl in der übergeordneten Tabelle als auch in der verknüpften Tabelle vorhanden sind. Erforderlich, wenn on nicht angegeben wird.
cardinality String Dies ist optional. Wird standardmäßig auf many_to_one festgelegt. Die Beziehung zwischen der Quelle und der verknüpften Tabelle. Legen Sie diese Eigenschaft fest, one_to_many um eine Tabelle zu aggregieren, die mehrere übereinstimmende Zeilen pro Quellzeile als separate Faktenquelle enthält. Siehe 1:n-Verknüpfungen.
joins Array Dies ist optional. Eine Liste der geschachtelten Verknüpfungsdefinitionen für die Snowflake-Schemamodellierung. Siehe Verfügbarkeit der Metrikansichtsfeatures für Mindestlaufzeitanforderungen.
rely Karte Dies ist optional. Verspricht über die Verknüpfung, auf die sich die Analyse verlassen kann, um effizientere Abfragepläne zu erstellen. Siehe Optimieren von Verknüpfungen mit rely.

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 Verknüpfung muss einer n:1-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

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)

Note

Der source Namespace verweist auf Spalten aus der Quelle der Metrikansicht, während eine Verknüpfung name auf Spalten aus dieser verknüpften Tabelle verweist. In , source.l_orderkey = orders.o_orderkey bezieht sich beispielsweise sourceauf die verknüpfte Tabelle und lineitem bezieht orders sich auf sie. Wenn in einer on Klausel kein Präfix angegeben wird, wird standardmäßig auf die verknüpfte Tabelle verwiesen.

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

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

1:n-Verknüpfungen

Das cardinality Feld legt die Beziehung zwischen der Quelle und einer verknüpften Tabelle fest. many_to_oneStandardmäßig wird die verknüpfte Tabelle als Bemaßungssuche behandelt. Legen Sie cardinality: one_to_many fest, dass die verknüpfte Tabelle als Faktenquelle behandelt wird, die das Modul unabhängig vom Quellkorn aggregiert, wodurch eine einzelne Quellzeile mit mehreren Zeilen in der verknüpften Tabelle übereinstimmt. 1:n-Joins erfordern Databricks Runtime 18.1 oder höher und YAML-Spezifikationsversion 1.1. Siehe Verfügbarkeit der Funktion „Metrikansicht“.

Die folgenden Regeln gelten für 1:n-Verknüpfungen:

  • Eine 1:n-Spalte kann nicht in einer fields Definition verwendet werden, da ein Feld in einen einzelnen Wert pro Quellzeile aufgelöst werden muss.
  • Eine einzelne Aggregationsfunktion muss auf Spalten aus einer Quelle verweisen. Sie können Arithmetik auf die Ergebnisse separater Aggregationen anwenden, z count(orders.order_id) / count(*). B. .
  • Alle Nachfolger einer 1:n-Verknüpfung müssen ebenfalls sein one_to_many. Gleichgeordnete Verknüpfungen auf oberster Ebene können Kardinalitäten kombinieren.
  • Verweisen Sie auf eine Spalte in einer geschachtelten Verknüpfung mit ihrem vollständigen Punktpfad durch die Verknüpfungsnamen, z orders.order_items.item_id. B. .

Im folgenden Beispiel wird orders eine Verknüpfung zu einer customers Quelle hergestellt cardinality: one_to_many , sodass Bestellmaße aggregiert werden, ohne Kundenzeilen zu duplizieren:

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)

Konzeptionelle Details und geschachtelte und gleichgeordnete Verknüpfungsbeispiele finden Sie unter Join-Kardinalität.

Optimieren von Verknüpfungen mit rely

Verwenden Sie das rely Feld für eine Verknüpfung, um Garantien für die Beziehung zu deklarieren, die der Abfrageanalyse bei der Planung von Abfragen verwendet. Diese Garantien ermöglichen es dem Modul, Abfragen effizienter zu planen und gescannte Daten zu reduzieren, insbesondere, wenn Felder aus der verknüpften Tabelle in Filtern referenziert werden.

Die rely Karte unterstützt die folgenden Felder:

Feld Typ Description
at_most_one_match Boolean Dies ist optional. Wird standardmäßig auf false festgelegt. Wenn true, deklariert, dass höchstens eine Zeile in der verknüpften Tabelle jeder Zeile in der Quelle entspricht (eine n:1-Beziehung, die nicht ausgeblendet wird).

Warning

Wird nur festgelegt at_most_one_match: true , wenn die Verknüpfung n:1 ist. Diese Beziehung wird zur Laufzeit nicht überprüft. Wenn mehrere Zeilen in der verknüpften Tabelle mit einer einzelnen Quellzeile übereinstimmen, geben Measures (z SUM . B. und COUNT) falsche Ergebnisse zurück.

Das folgende Beispiel aktiviert at_most_one_match eine n:1-Verknüpfung von orders zu customer. Abfragen, die nach Kundenattributen filtern oder gruppieren, profitieren am meisten:

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)

Felder

Note

fields und dimensions sind gleichwertige Schlüsselwörter in einer Definition der Metrikansicht. fields ist der bevorzugte Begriff und wird in dieser Dokumentation verwendet. Der Katalog-Explorer-Editor beschriftt diese Spalten "Fields", aber das generierte YAML verwendet das dimensions Schlüsselwort. Vorhandene Metrikansichten, die dimensions weiterhin funktionieren, und beide Schlüsselwörter werden für neue oder aktualisierte Definitionen akzeptiert.

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

Ein Feld kann entweder sein:

  • Eine kategorisierte oder gruppierende Spalte, z. B. eine Region, einen Status oder eine Abteilung.
  • Eine nicht aggregierte numerische Spalte, z. B. ein Alter, ein Preis oder eine Menge. Numerische Felder können zur Abfragezeit mithilfe von SQL-Funktionen wie SUM oder AVG.

Jede Felddefinition enthält die folgenden Eigenschaften:

Property Typ Description
name String Erforderlich für explizite Spaltenausdrücke. Der Spaltenalias für das Feld. Lassen Sie es für Wildcardausdrücke weg, wobei Azure Databricks Namen von der Quelle ableiten. Siehe Massenimportfelder und Measures mit Wildcards.
expr String Required. Ein SQL-Ausdruck, der auf Spalten aus den Quelldaten oder auf ein zuvor definiertes Feld verweisen kann. Dies kann ein Wildcard sein, um alle Spalten aus der Quelle oder einer verknüpften Tabelle zu importieren. Siehe Massenimportfelder und Measures mit Wildcards.
comment String Dies ist optional. Beschreibung des Felds. Wird in Unity-Katalog- und Dokumentationstools angezeigt.
display_name String Dies ist optional. Bezeichnung, die in Visualisierungstools angezeigt wird. Auf 255 Zeichen beschränkt. Erfordert YAML-Spezifikation 1.1. Siehe Verfügbarkeit der Funktion „Metrikansicht“.
format Karte Dies ist optional. Formatspezifikation für die Anzeige von Werten. Erfordert YAML-Spezifikation 1.1. Siehe Formatspezifikationen.
synonyms Array Dies ist optional. Alternative Namen für KI- und BI-Tools zum Ermitteln des Felds. Bis zu 10 Synonyme, jeweils auf 255 Zeichen beschränkt. Erfordert YAML-Spezifikation 1.1. Siehe Synonyme.

Warning

Zeichenfolgenähnliche metrische Ansichtsfelder sind immer STRING, auch wenn die Quellspalte ist CHAR oder VARCHAR. Da CHAR(n) Platzabstand verloren geht, können Vergleiche unterschiedliche Ergebnisse zurückgeben. Zum Beispiel entspricht column = 'COLLEGE' einem CHAR(10)-Wert in der Quelltabelle (der mit Leerzeichen aufgefüllt ist), aber nicht dem Feld der Metrikansicht.

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

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. Kennzahlen können auf Basisspalten in den Quelldaten, zuvor definierten Feldern oder zuvor definierten Kennzahlen verweisen.

Jede Measuredefinition enthält die folgenden Felder:

Feld Typ Description
name String Erforderlich für explizite Measureausdrücke. Der Alias für das Measure. Lassen Sie es für Wildcardausdrücke weg, wobei Azure Databricks Namen von der Quelle ableiten. Siehe Massenimportfelder und Measures mit Wildcards.
expr String Required. Ein SQL-Ausdruck, der mindestens eine Aggregatfunktion enthält. Dies kann ein Wildcard sein, um alle Measures aus einer metrischen Ansichtsquelle zu importieren. Siehe Massenimportfelder und Measures mit Wildcards.
comment String Dies ist optional. Beschreibung der Maßnahme. Wird in Unity-Katalog- und Dokumentationstools angezeigt.
display_name String Dies ist optional. Bezeichnung, die in Visualisierungstools angezeigt wird. Auf 255 Zeichen beschränkt. Erfordert YAML-Spezifikation 1.1. Siehe Verfügbarkeit der Funktion „Metrikansicht“.
format Karte Dies ist optional. Formatspezifikation für die Anzeige von Werten. Erfordert YAML-Spezifikation 1.1. Siehe Formatspezifikationen.
synonyms Array Dies ist optional. Alternative Namen für KI- und BI-Tools, um das Measure zu ermitteln. Bis zu 10 Synonyme, jeweils auf 255 Zeichen beschränkt. Erfordert YAML-Spezifikation 1.1. Siehe Verfügbarkeit der Funktion „Metrikansicht“.
window Array Dies ist optional. Fensterspezifikationen für fensterierte, kumulative oder semiadditive Aggregationen. Wenn nicht angegeben, verhält sich das Measure als Standardaggregat. Siehe Fenstermaße.

Eine Liste der Aggregatfunktionen finden Sie unter " Aggregatfunktionen ".

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

Massenimport von Feldern und Kennzahlen mit Platzhaltern

Gilt für: Databricks Runtime 18.2 und höher mit YAML-Spezifikation 1.1

In einer fields oder measures einer Definition können Sie einen Platzhalter (*) im expr Feld verwenden, um alle Spalten aus der Quelle oder einer verknüpften Tabelle zu importieren, ohne jede aufzulisten. Dies ist nützlich, wenn Sie möchten, dass jede Spalte aus einer upstream-Ressource verfügbar gemacht wird, ähnlich SELECT * wie in einer Standardansicht. Azure Databricks erweitert den Feldhalter auf konkrete Spalten, wenn Sie die Metrikansicht erstellen oder ersetzen, und leitet jeden Spaltennamen vom Quellspaltennamen ab.

Wie explizite Spaltendefinitionen werden Beim Erstellen der Metrikansicht Wildcardausdrücke erweitert. Wenn Sie der Quelle später hinzugefügte Spalten aufnehmen möchten, erstellen Sie die Metrikansicht mit CREATE OR REPLACE oder ALTER.

Wildcards unterstützen die folgenden Formulare:

Syntax Description
source.* Importieren Sie alle Spalten aus der metrischen Ansichtsquelle.
<join>.* Importieren Sie alle Spalten aus einer verknüpften Tabelle, auf die durch den Verknüpfungsnamen verwiesen wird. Geschachtelte Verknüpfungen verwenden den vollständigen Punktpfad, z customer.nation.*. B. .
<target>.* EXCEPT (col1, col2, ...) Importieren Sie alle Spalten aus dem Ziel mit Ausnahme der aufgelisteten Spalten.
<target>.<struct>.* Erweitern Sie die Felder einer STRUCT Spalte in separate Spalten.

Die folgenden Regeln gelten für Wildcardausdrücke:

  • Lassen Sie das name Feld weg. Azure Databricks Spaltennamen von der Quelle abgeleitet, ist daher name für einen Wildcardausdruck nicht zulässig.
  • Semantische Metadaten sind für einen Wildcardausdruck nicht zulässig. Legen Sie auf einem Wildcard nicht fest, commentoder display_nameformat legen synonymsSie sie nicht fest. Um einer bestimmten Spalte Metadaten hinzuzufügen, schließen Sie sie aus dem Wildcardfeld aus EXCEPT , und definieren Sie sie explizit.
  • In einer measures Definition importiert ein Wildcard Measures nur aus einer metrischen Ansichtsquelle. Basistabellen haben keine Measures, sodass ein Wildcard ohne Measures erweitert wird, wenn die Quelle eine Basistabelle ist.
  • Sie können in einem späteren fields Oder measures Ausdruck nicht auf eine von einem Wildcard importierte Spalte verweisen, indem Sie den abgeleiteten Namen verwenden. Verweisen Sie stattdessen auf die Quellspalte mit dem vollständigen Pfad.

Auflösen von Namenskonflikten

Wenn Sie Spalten aus mehreren Quellen mit einem Wildcard importieren, kollidieren Spalten, die einen Namen teilen (z id . B. oder date) kollidieren und beim Speichern der Definition einen Fehler verursachen. Um eine Kollision zu beheben, schließen Sie die Spalte von den einzelnen Wildcards aus EXCEPT, und definieren Sie sie dann explizit mit einem eindeutigen Namen:

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

Beispiel für Einen Wildcard

Die folgende Definition importiert alle Spalten aus der Quelle und aus einer verknüpften Tabelle, schließt zwei Spalten aus und definiert eine Spalte explizit, um Metadaten hinzuzufügen:

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'

Fenstermaße

Important

Dieses Feature ist experimentell.

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:

Feld Typ Description
order String Required. Das Feld, das die Reihenfolge des Fensters bestimmt. (1)
range String Required. Der Umfang des Fensters. Siehe unterstützte range Werte.
semiadditive String Required. Aggregationsmethode. Unterstützte Werte: first oder last
offset String Dies ist optional. Erfordert Databricks Runtime 18.1 und YAML-Spezifikation Version 1.1 oder höher. Verschiebt den Fensterrahmen um ein festes Intervall rückwärts oder vorwärts entlang des order Felds. Der Wert ist der Form <n> <period>, wobei n eine signierte ganze Zahl ist (negativ sieht rückwärts, positive Blicke vorwärts) und period ist eine von day, , days, , month, months, , oder yearyears. Beispiele: -12 month, 1 year, -3 days, 7 day. Das order Feld muss eine Datums- oder Zeitstempelspalte sein. offset hat keine Auswirkung auf range: all. Wenn der verschobene Frame außerhalb der verfügbaren Daten liegt, wird das Measure ausgewertet.NULL Verwendungs- und Arbeitsbeispiele finden Sie unter offset "Verschieben des Fensterrahmens".

(1) Das referenzierte Feld muss deterministisch sein. Nicht deterministische Ausdrücke wie rand(), uuid()oder current_timestamp() erzeugen unvorhersehbare Fensterbestellungen und können zu falschen Aggregationsergebnissen führen.

Unterstützte range Werte

  • current: Zeilen, bei denen der Fensterreihenfolgewert dem Wert der Verankerungszeile entspricht.
  • cumulative: Alle Zeilen, in denen der Fensterreihenfolgewert kleiner oder gleich dem Wert der Verankerungszeile ist.
  • trailing <value> <unit> [inclusive | exclusive]: Zeilen aus der Verankerungszeile, die um die angegebenen Zeiteinheiten rückwärts gehen, z. B trailing 7 day. . Der optionale inclusiveexclusive Oder Modifizierer erfordert Databricks Runtime 18.1 und YAML-Spezifikation, Version 1.1 oder höher, und steuert, ob die Verankerungszeile im Fenster enthalten ist. Der Standardwert lautet exclusive. Siehe Ankerzeile ein- oder ausschließen.
  • leading <value> <unit> [inclusive | exclusive]: Zeilen aus der Verankerungszeile, die von den angegebenen Zeiteinheiten vorwärts ausgeführt werden, z. B leading 3 month. . Der optionale inclusiveexclusive Oder Modifizierer erfordert Databricks Runtime 18.1 und YAML-Spezifikation, Version 1.1 oder höher, und steuert, ob die Verankerungszeile im Fenster enthalten ist. Der Standardwert lautet exclusive. Siehe Ankerzeile ein- oder ausschließen.
  • all: Alle Zeilen unabhängig vom Fensterreihenfolgewert.

Beispiel für Fenstermaß

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

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

Materialisation

Important

Dieses Feature befindet sich in der Public Preview.

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.

Note

Sie können keine Metrikansicht materialisieren, die Parameter definiert.

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

Feld Typ Description
schedule String Dies ist optional. Zeitplan aktualisieren. Verwendet dieselbe Syntax wie die Zeitplanklausel für materialisierte Ansichten. Ohne Angabe werden Materialisierungen nur manuell aktualisiert. Die TRIGGER ON UPDATE-Klausel wird nicht unterstützt.
mode String Required. Muss auf relaxed festgelegt sein.
materialized_views Array Required. Liste der materialisierten Ansichten, die materialisiert werden sollen. Für jeden Eintrag sind die unten beschriebenen Felder erforderlich.

Jeder Eintrag enthält materialized_views die folgenden Felder:

Feld Typ Description
name String Required. Der Name der Materialisierung.
type String Required. Art der Materialisierung. Unterstützte Werte: aggregated (erfordert dimensions, measuresoder beide) oder unaggregated.
dimensions Array Konditional. Liste der zu materialisierenden Feldnamen. Erforderlich, falls type angegeben aggregated und nicht measures angegeben.
measures Array Konditional. Liste der zu materialisierenden Measurenamen. Erforderlich, falls type angegeben aggregated und nicht dimensions angegeben.
cluster_by Object Dies ist optional. Gruppieren von Spalten für die Materialisierung, entspricht der CLUSTER BY Klausel in einer materialisierten Ansicht. Geben Sie eine Liste von Spaltennamen an, oder legen Sie cols fest auto: true , dass Databricks die Clusterspalten automatisch auswählen kann.
partition_by Array Dies ist optional. Liste der Spalten, um die Materialisierung zu partitionieren, entsprechend der PARTITION BY Klausel in einer materialisierten Ansicht.

Note

Der Materialisierungsblock verwendet das dimensions: Schlüsselwort anstelle von fields:. Wird beim dimensions: Auflisten von Feldern zum Materialisieren verwendet, auch wenn ihre Definition auf oberster Ebene verwendet fields:wird.

Materialisierungsbeispiel

Im folgenden Beispiel wird eine Metrikansicht mit mehreren Materialisierungen definiert:

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

Spaltennamenverweise

Wenn Sie auf Spaltennamen verweisen, die Leerzeichen oder Sonderzeichen in YAML-Ausdrücken enthalten, schließen Sie den Spaltennamen in Backticks ein. 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

Die folgenden Beispiele zeigen, wie Spaltenverweise je nach den enthaltenen Zeichen formatiert werden.

Keine Leerzeichen

Quellspalte: revenue

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

Verwenden Sie doppelte Anführungszeichen, einfache Anführungszeichen oder keine Anführungszeichen um den Spaltennamen.

Spaltenname mit Leerzeichen

Quellspalte: `First Name`

expr: '`First Name`'

Verwenden Sie Backticks, um Leerzeichen zu maskieren. Schließen Sie den gesamten Ausdruck in doppelte Anführungszeichen ein.

Spaltennamen mit Leerzeichen in einem SQL-Ausdruck

Quellspalten: `First Name`, `Last Name`

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

Wenn der Ausdruck nicht mit einem Backtick beginnt, sind doppelte Anführungszeichen nicht erforderlich.

Spaltenname mit Anführungszeichen

Quellspalte: "name"

expr: '`"name"`'

Verwenden Sie Backticks, um die doppelten Anführungszeichen im Spaltennamen zu escapen. Schließen Sie den Ausdruck in einfache Anführungszeichen ein.

Ausdrücke mit Doppelpunkten

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

Note

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.

Mehrzeilige Ausdrücke

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

Note

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

Upgrade auf YAML 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 geschrieben wurden.
  • Kommentare im Unity-Katalog: Kommentare, die im Unity-Katalog für die Metrikansicht oder die zugehörigen Spalten 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.

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

Warning

Beim Ausführen ALTER VIEW werden Unity-Katalogkommentare entfernt, es sei denn, sie werden explizit in die comment Felder der YAML-Definition eingeschlossen. Informationen zum Beibehalten von Kommentaren im Unity-Katalog finden Sie unter Option 2.

Option 2: Beibehalten von Unity-Katalogkommentaren

Note

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, behält die YAML-Editor-Benutzeroberfläche automatisch Ihre Unity-Katalogkommentare bei.

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

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

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

  • Last updated on