Tabellarische Modelldefinitionssprache (TMDL)

gilt für: SQL Server 2016 und höher Analysis Services Azure Analysis Services Fabric/Power BI Premium

Tabular Model Definition Language (TMDL) ist eine Objektmodelldefinitionssyntax für tabellarische Datenmodelle auf Kompatibilitätsebene 1200 oder höher.

Zu den wichtigsten Elementen von TMDL gehören:

• Vollständige Kompatibilität mit dem gesamten tabellarischen Objektmodell (TOM). Jedes TMDL-Objekt macht dieselben Eigenschaften wie TOM verfügbar.
• Textbasiert und für menschliche Interaktion und Lesbarkeit optimiert. TMDL verwendet eine Grammatiksyntax ähnlich yaML. Jedes TMDL-Objekt wird in Text mit minimalen Trennzeichen dargestellt und verwendet einen Einzug, um beziehungen zwischen übergeordneten und untergeordneten Elementen zu markieren.
• Bessere Bearbeitungserfahrung, insbesondere für Eigenschaften mit Einbettungsausdrücken aus unterschiedlichen Inhaltstypen, z. B. Data Analysis Expression (DAX) und M.
• Besser für die Zusammenarbeit aufgrund der Ordnerdarstellung, in der jedes Modellobjekt eine einzelne Dateidarstellung aufweist, wodurch die Quellcodeverwaltung einfacher wird.

Ein wichtiger Aspekt von TMDL ist die Verwendung eines Leerzeicheneinzugs, um eine TOM-Objektstruktur zu kennzeichnen. Das folgende Beispiel zeigt, wie einfach es ist, ein tabellarisches Modell bei Verwendung von TMDL darzustellen:

database Sales
	compatibilityLevel: 1567

model Model    
    culture: en-US    

table Sales
    
    partition 'Sales-Partition' = m
        mode: import
        source = 
            let
                Source = Sql.Database(Server, Database)
                …
    
    measure 'Sales Amount' = SUMX('Sales', 'Sales'[Quantity] * 'Sales'[Net Price])
        formatString: $ #,##0
   
    column 'Product Key'
        dataType: int64
        isHidden
        sourceColumn: ProductKey
        summarizeBy: None
 
    column Quantity
        dataType: int64
        isHidden
        sourceColumn: Quantity
        summarizeBy: None

    column 'Net Price'
        dataType: int64
        isHidden
        sourceColumn: "Net Price"
        summarizeBy: none

table Product
    
    partition 'Product-Partition' = m
        mode: import
        source = 
            let
                Source = Sql.Database(Server, Database),
                …

    column 'Product Key'
        dataType: int64
        isKey
        sourceColumn: ProductKey
        summarizeBy: none

relationship cdb6e6a9-c9d1-42b9-b9e0-484a1bc7e123
    fromColumn: Sales.'Product Key'
    toColumn: Product.'Product Key'

role Role_Store1
    modelPermission: read

    tablePermission Store = 'Store'[Store Code] IN {1,10,20,30}

expression Server = "localhost" meta [IsParameterQuery=true, Type="Text", IsParameterQueryRequired=true]

expression Database = "Contoso" meta [IsParameterQuery=true, Type="Text", IsParameterQueryRequired=true]

TMDL-Ordnerstruktur

Im Gegensatz zu TMSL verwendet TMDL eine Ordnerstruktur. Die Standardordnerstruktur hat nur eine Ebene von Unterordnern, alle mit TMDL-Dateien innerhalb:

• kulturen
• Perspektiven
• Rollen
• Tabellen

Und Stammdateien für:

• Datenbank
• Modell
• Beziehungen
• Ausdrücke
• Datenquellen

Hier ist ein Beispiel für einen TMDL-Ordner:

Zu den Definitionen gehören:

• Eine Datei für die Datenbankdefinition.
• Eine Datei für die Modelldefinition.
• Eine Datei für alle Datenquellen im Modell.
• Eine Datei für alle Ausdrücke im Modell.
• Eine Datei für alle Beziehungen im Modell.
• Eine Datei für jedes kulturlinguistischen Schemas.
• Eine Datei für jeder Perspektive.
• Eine Datei für jeder Rolle.
• Eine Datei für jeder Tabelle.
• Alle inneren Metadateneigenschaften von Tabellen (Column, Hierarchies, Partitions,...) metadaten befinden sich in der tmDL-Datei der übergeordneten Tabelle.

TMDL-API

Ähnlich wie Tabellenmodell scripting Language (TMSL), gibt es eine Klasse zum Behandeln der TMDL-Serialisierung. Für TMDL ist die Klasse TmdlSerializerunter dem Microsoft.AnalysisServices.Tabular Namespace.

Die TmdlSerializer-Klasse macht Methoden zum Serialisieren und Deserialisieren von TMDL-Dokumenten verfügbar:

Serialisierung von Ordnern

public static void SerializeDatabaseToFolder (Database database, string path)

• Empfängt ein TOM-Datenbankobjekt und den TMDL-Ausgabepfad.
• Serialisiert die TOM-Datenbank in eine TMDL-Ordnerdarstellung.

Erfahren Sie mehr darüber, wie Sie in einen Ordnerserialisieren.

public static Database DeserializeDatabaseFromFolder (string path)

• Empfängt einen vollständigen Pfad zu einem TMDL-Ordner.
• Gibt die TOM-Datenbankobjektdarstellung des TMDL-Ordners zurück.

Erfahren Sie mehr darüber, wie Sie aus Ordnerndeserialisieren.

Serialisierung von Zeichenfolgen

public static string SerializeObject (MetadataObject object, bool qualifyObject = true)

• Empfängt ein TOM-Objekt und gibt seine TMDL-Textdarstellung zurück.

Erfahren Sie mehr darüber, wie sie ein Objekt in eine Zeichenfolgeserialisieren.

Stream Serialisierung

Sie können TMDL in/von Datenströmen serialisieren/deserialisieren, sodass Sie ein TOM-Objekt in Bytestreams für Speicher, Übertragung und Interoperabilität auf allen Plattformen konvertieren können. Mit der Stream-API können Sie auch steuern, welche TMDL-Dokumente geladen werden und welche TMDL-Dokumente ausgegeben werden.

Die TMDL Stream Serialisierung wird von der MetadataSerializationContext Klasse behandelt.

Erfahren Sie mehr darüber, wie Sie mithilfe von Streamsin/aus TMDL serialisieren.

TMDL-Sprache

Objektdeklaration

Mit Ausnahme des Serverobjekts macht TMDL die gesamte Database-Objektstruktur im Microsoft.AnalysisServices.Tabular-Namespaceverfügbar.

Ein TMDL-Objekt wird deklariert, indem der TOM-Objekttyp gefolgt von seinem Namen angegeben wird. Im folgenden Codebeispiel folgt jeder Objekttyp: model, table, column folgt einem Objektnamen.

model Model    
    culture: en-US    

table Sales
    
    measure Sales = SUM(…)
        formatString: $ #,##0

    column 'Customer Key'
        datatype: int64
        sourceColumn: CustomerKey

Objekte wie partition oder measure verfügen über Standardeigenschaften, die nach dem Gleichheitstrennzeichen (=) in derselben Zeile der Objektdeklaration oder in der folgenden Zeile für einen mehrzeiligen Ausdruckzugewiesen werden können:

table Sales

    partition Sales-Part1 = m
        mode: import
        ...        
    
    measure Sales = SUM(…)
        formatString: $ #,##0

    measure 'Sales (ly)' = 
            var ly = ...
            return ly
        formatString: $ #,##0

Der Name des TMDL-Objekts muss in einfache Anführungszeichen (') eingeschlossen werden, wenn er eines der folgenden Zeichen enthält:

• Punkt (.)
• Gleich (=)
• Doppelpunkt (:)
• Einfaches Anführungszeichen (')
• Leerzeichen ( )

Wenn ein Objektname einzelne Anführungszeichen (') enthält, verwenden Sie zwei einfache Anführungszeichen, um es zu escapeen.

Objekteigenschaften

Objekteigenschaften werden nach der Objektdeklaration oder dem mehrzeiligen Ausdruck der Objektstandardeigenschaft angegeben. Objekteigenschaftswerte werden nach dem Doppelpunkt (:) Trennzeichen angegeben. Zum Beispiel:

table Sales
    lineageTag: e9374b9a-faee-4f9e-b2e7-d9aafb9d6a91    

    column Quantity
        dataType: int64
        isHidden
        isAvailableInMdx: false
        sourceColumn: Quantity

    measure 'Sales Amount' = 
            var result = SUMX(...)
            return result
  formatString: $ #,##0
  displayFolder: " My ""Amazing"" Measures"

Die folgenden Regeln gelten für Eigenschaftswerte:

• Der Wert muss sich in derselben Zeile befinden, die auf den Doppelpunkt folgt und nicht über mehrere Zeilen verfügt.

• Texteigenschaftenwerte

  • Führende und nachfolgende Doppelte Anführungszeichen sind optional und werden während der Serialisierung automatisch entfernt.
  • Muss in doppelte Anführungszeichen (") eingeschlossen werden, wenn der Text nachfolgende oder führende Leerzeichen enthält.
  • Wenn der Wert doppelte Anführungszeichen enthält, verwenden Sie zwei doppelte Anführungszeichen, um sie zu escapen (siehe displayFolder Eigenschaft im obigen Codebeispiel).

• boolesche Eigenschaften können mithilfe der Standardmäßigen Schlüssel-Wert-Paarsyntax festgelegt werden, z. B. mit der eigenschaft 'isAvailableInMdx' im vorherigen Beispiel. Sie können auch mithilfe einer Tastenkombinationssyntax festgelegt werden, bei der nur der Eigenschaftsname deklariert und true impliziert wird. Siehe z. B. die Eigenschaft "isHidden" im vorherigen Beispiel.

Benannte Objektverweise

Einige Objekteigenschaften enthalten Verweise auf andere Modellobjekte, z. B.:

• Spaltenverweis in Hierarchieebenen.
• sortByColumn-Bezug in jeder Tabellenspalte.
• Tabellen-/Spalten-/Measurebezug in Perspektiven.

In TMDL werden Verweise mithilfe des Objektnamens erstellt und folgen den gleichen Escape- und Ein-Anführungszeichen (') umschließende Anforderungen der Objektdeklaration. Im folgenden Codebeispiel werden Objekteigenschaften angezeigt, die einen Verweis auf ein anderes Objekt enthalten: column.sortByColumn, level.column, perspectiveMeasure.measure und perspectiveTable.table.

table Product

    column Category
        sortByColumn: 'Category Order'    

 hierarchy 'Product Hierarchy'

  level Category   
   column: Category  
 

perspective Product

 perspectiveTable Product

        perspectiveMeasure '# Products'

Wenn auf einen vollqualifizierten Namen verwiesen werden muss, verwendet TMDL Punkt- Notation, um auf ein Objekt zu verweisen, z. B.: 'Table 1'.'Column 1'

Untergeordnete Objekte

Die TOM-Objektstruktur enthält untergeordnete Objekte an vielen Stellen und auf unterschiedlichen Ebenen. Zum Beispiel:

• Ein Modellobjekt enthält Tabellen-, Rollen- und Ausdrucksobjekte.
• Ein Tabellenobjekt enthält Spalten-, Measure- und Hierarchieobjekte.

TMDL deklariert keine untergeordneten Auflistungen explizit. Stattdessen bilden alle anwendbaren untergeordneten Elemente im Bereich ihres jeweiligen übergeordneten Elements implizit die Elemente der entsprechenden Auflistung. Beispielsweise werden alle Spaltenelemente im Bereich einer bestimmten Tabelle zu Elementen der Spaltenauflistung dieser Tabelle in TOM, wie hier gezeigt:

table Sales

    measure 'Sales Amount' = SUMX('Sales', [Quantity] * [Net Price])

    measure 'Total Quantity' = SUM('Sales'[Quantity])

    measure 'Sales Amount YTD' = TOTALYTD([Sales Amount], 'Calendar'[Date])    

Untergeordnete Objekte müssen nicht zusammenhängend sein. Sie können z. B. Spalten und Measures in beliebiger Reihenfolge und bestimmt deklarieren.

Standardeigenschaften

Einige Objekttypen weisen eine Standardeigenschaft auf, die meistens wie Ausdrückebehandelt werden. Die Standardeigenschaft ist objekttypspezifisch. Falls zutreffend, wird der Eigenschaftswert oder Ausdruck nach dem Gleichheitszeichen (=) - nach der Abschnittsdeklaration angegeben.

Unterstützte Syntax:

• Der Wert wird in derselben Zeile wie die Abschnittsüberschrift angegeben.
• Der Wert wird als mehrzeiligen Ausdruck nach der Abschnittsüberschrift angegeben.

Im folgenden Codebeispiel sind Sales Amount und Partitions-Sales-Partition1 eine einzelne Zeile und Quantity mehrere Zeilen sind:

table Sales

    measure 'Sales Amount' = SUM(...)
        formatString: $ #,##0

    measure Quantity = 
            var result = SUMX (...)
            return result
        formatString: #,##0

    partition Sales-Partition1 = m
  mode: import
  source =
   let
       ...
   in
       finalStep

Ausdrücke

Es gibt Objekteigenschaften, die beim Verwenden einer Texteigenschaft in TOM spezielle Analyse in TMDL erhalten. Der gesamte Text ist schreibgeschützt, da er Sonderzeichen wie Anführungszeichen oder eckige Klammern in M- oder DAX-Ausdrücken enthalten kann. Ausdrücke können mehrzeilig oder einzeilig sein. Wenn mehrere Zeilen vorhanden sind, müssen sie sich unmittelbar nach der Eigenschafts- oder Objektdeklaration in der Zeile befinden.

Ein Ausdruckswert in TMDL wird wie im folgenden Beispiel wie im folgenden Beispiel angegeben, um ein Gleichheitszeichen (=) anzugeben:

table Table1

    partition 'partition 1' = m
        mode: import
        source =
            let
            ...
            in
                finalStep
    
    measure Measure1 = SUM(...)

    measure Measure2 =
            var result = SUMX ( 
                ...
            )
            return result
        formatString: $ #,##0

Die folgenden speziellen Regeln gelten für Ausdrücke:

• Mehrzeilige Ausdrücke müssen eine Ebene tiefer in die übergeordneten Objekteigenschaften eingezogen werden, und der gesamte Ausdruck muss sich innerhalb dieser Einzugsebene befinden.
• Alle äußeren Einzugs-Leerzeichen werden über die eingerückte Ebene des übergeordneten Objekts hinaus entfernt.
• Vertikale Leerzeichen (leere Zeilen ohne Leerzeichen) sind zulässig und gelten als Teil des Ausdrucks.
• Nachfolgende leere Zeilen und Leerzeichen werden entfernt.
• Wenn Sie einen anderen Einzug erzwingen oder nachfolgende leere Zeilen oder Leerzeichen beibehalten möchten, verwenden Sie die drei umschließenden Backticks (```).
• Standardmäßig wird der TMDL-Serializer mit Hintergrundzeichen eingeschlossen, wenn der Ausdruckswert etwas enthält, das zu einer Änderung auf Roundtrips führen kann (z. B. nachfolgende Leerzeichen, leere Zeilen mit Leerzeichen).

Ausdrücke, die mit drei Backticks (```) eingeschlossen sind, sind schreibgeschützt, einschließlich Einzug, Leerzeilen und Leerzeichen. Das Trennzeichen sollte unmittelbar nach dem Gleichheitszeichen (=) und der Zeile nach dem Ausdruck angewendet werden und kann danach nichts haben, wie im folgenden Beispiel:

table Table1

    partition partition1 = m
        mode: import
        source = ```
            let
            ...
            in
                finalStep

            ```

    measure Measure1 = ```
                var myVar = Today()
                …
                return result
            ```

Die Verwendung der drei Backticks (```) Trennzeichen ist optional und nur in eindeutigen Situationen erforderlich. In den meisten Fällen stellt die Verwendung des korrekten Einzugs und der Objektdeklaration die korrekte Analyse des ausdrucks sicher, den Sie der Eigenschaft hinzufügen.

Wenn der Ausdruck in Backticks eingeschlossen ist, gelten die folgenden Regeln:

• Alles zwischen drei Backticks (```) wird als Teil des Multiblockausdrucks betrachtet und TMDL-Einzugsregeln werden nicht angewendet. Das Endtrennzeichen bestimmt den Einzug innerhalb des Ausdrucks.
• Der relative Einzug innerhalb des Ausdrucks wird beibehalten. Das Endtrennzeichen (```) bestimmt die linke Grenze des Ausdrucks (siehe "Measure1" im vorherigen Beispiel).

Die folgenden Eigenschaften werden als Ausdrücke behandelt:

Standardeigenschaften nach Objekttyp

Die folgende Tabelle zeigt die Standardeigenschafts- und Ausdruckssprache nach Objekttyp:

Beschreibungen

TMDL bietet erstklassige Unterstützung für Beschreibungen. Für Modelldokumentationszwecke empfiehlt es sich, Beschreibungen für jedes TOM-Objekt bereitzustellen. TMDL behandelt Beschreibungen als spezielle Eigenschaft mit expliziter Syntaxunterstützung. Im Anschluss an die Beispiele aus vielen anderen Sprachen werden Beschreibungen über jede Objektdeklaration mit dreifacher Schrägstrichsyntax (///) angegeben.

Zwischen dem Ende des Beschreibungsblocks und dem Objekttyptoken ist kein Leerzeichen zulässig.

Beschreibungen können über mehrere Zeilen aufgeteilt werden. Der TMDL-Serialisierer unterbricht Objektbeschreibungen in mehrere Zeilen, um ausgegebene Dokumentzeilen unter der maximalen Länge beizubehalten. Die standardmäßige maximale Länge beträgt 80 Zeichen.

/// Table Description
table Sales

    /// This is the Measure Description
    /// One more line
    measure 'Sales Amount'' = SUM(...)
        formatString: #,##0

Partielle Deklaration

TMDL erzwingt keine Objektdeklaration im selben Dokument. Es ähnelt jedoch C#-Teilklassen wo es möglich ist, die Objektdefinition zwischen mehreren Dateien aufzuteilen. Sie können beispielsweise eine Tabellendefinition in einer [Table].tmdl-Datei deklarieren und dann alle Measures aus allen Tabellen haben, die in einer einzigen [measures].tmdl-Datei definiert sind, wie hier gezeigt:

table Sales

    measure 'Sales Amount' = SUM(…)
        formatString: $ #,##0

table Product

    measure CountOfProduct = COUNTROWS(…)

Um einen Analysefehler zu vermeiden, kann dieselbe Eigenschaft nicht zweimal deklariert werden. Beispielsweise führt das Deklarieren von zwei Measures mit demselben Namen für dieselbe Tabelle in zwei verschiedenen TMDL-Dokumenten zu einem Fehler.

Objektverweise

Sie können mithilfe des Ref Schlüsselworts gefolgt vom Objekttyp und -namen auf ein anderes TMDL-Objekt verweisen.

Wenn Sie beispielsweise ein Column-Objekt mithilfe der Zeichenfolgen serialisierungs-API serialisieren, lautet das Ergebnis wie folgt:

ref table Table1
	column Column1
		datatype: int64
		sourceColumn: Column1

Deterministische Sammlungsbestellung

Das schlüsselwort ref wird auch verwendet, um die Sammlungsordnung auf TOM-<> TMDL-Roundtrips zu definieren und beizubehalten. Es ist besonders wichtig, Die Diffs der Quellcodeverwaltung auf TMDL-Objekten zu vermeiden, die in einzelne Dateien serialisiert werden: Tabellen, Rollen, Kulturen und Perspektiven. Das schlüsselwort "ref" wird in der tmDL-Datei des übergeordneten Objekts verwendet, um die Elementbestellung von TOM zu deklarieren:

model Model

ref table Calendar
ref table Sales
ref table Product
ref table Customer
ref table About

ref culture en-US
ref culture pt-PT

ref role 'Stores Cluster 1'
ref role 'Stores Cluster 2'

Die folgenden Regeln werden angewendet:

• Während der TMDL-Deserialisierung:
  • Objekte, auf die in TMDL verwiesen wird, aber mit fehlender TMDL-Datei, werden ignoriert.
  • Objekte, auf die nicht verwiesen wird, aber mit vorhandener TMDL-Datei, werden am Ende der Auflistung angefügt.
• Während der TMDL-Serialisierung:
  • Auf alle Auflistungsobjekte in TOM wird mithilfe des schlüsselworts ref verwiesen.
  • Auflistungen mit nur einem Element geben keinen Verweis aus.
  • Leere Zeilen werden nicht zwischen ref's ausgegeben, wenn derselbe Objekttyp vorhanden ist.

Eigenschaftswerttrennzeichen

Es gibt nur zwei Trennzeichen/Symbole zum Zuweisen eines Eigenschaftswerts:

• Gleich (=)

  • Wird bei der Objektdeklaration mit Standardeigenschaft (mehrere und einzelne Zeilen) verwendet.
  • Wird bei jeder Ausdruckseigenschaftverwendet, z. B. partition.expression

• Doppelpunkt (:)

  • Wird für jeden Nichtausdruck Eigenschaftswertverwendet. Einschließen von Eigenschaften, die Modellverweise enthalten.

Einrückung

TMDL verwendet strenge Leerzeicheneinzugsregeln zum Kennzeichnen der Struktur der TOM-Hierarchie. Ein TMDL-Dokument verwendet eine standardmäßige einzelne Tabulatorregel Einzugsregel.

Jedes Objekt kann drei Einzugsebenen aufweisen:

• Ebene 1 – Objektdeklaration
  • Ebene 2 – Objekteigenschaften
    • Ebene 3 : Mehrzeilige Ausdrücke der Objekteigenschaft

Innerhalb eines TMDL-Dokuments wird der Einzug in den folgenden Fällen angewendet:

• Zwischen einer Objektabschnittsüberschrift und den Eigenschaften des Objekts (Tabelle -> Eigenschaften).

  table Sales
      isHidden
      lineageTag: 9a48bea0-e5fb-40fa-9e81-f61288e31a02
  

• Zwischen einem Objekt und seinen untergeordneten Objekten (Tabelle -> Measures).

  table Sales
  
      measure 'Sales Amount' = SUMX(...)
  
      measure 'Total Quantity' = SUM(...)
  

• Zwischen einem Objekt und seinen mehrzeiligen Ausdrücken (Tabelle -> Measure -> Ausdruck).

  table Sales
  
      measure 'Sales Amount' = 
              var result = SUMX(...)
              return result
          formatString: $ #,##0
  

• Mehrzeilige Ausdrücke müssen eine Ebene tiefer als Objekteigenschaften eingezogen werden, und der gesamte Ausdruck muss sich innerhalb dieser Einzugsebene (siehe Ausdrücke) befindet.

Datenbank- und direkte untergeordnete Objekte von Model müssen nicht eingerückt werden, da sie implizit unter dem Stammmodell oder der Datenbank geschachtelt werden:

• Modell
• Tabellen
• Freigegebene Ausdrücke
• Rollen
• kulturen
• Perspektiven
• Beziehungen
• Datenquellen
• Abfragegruppen
• Anmerkungen auf Modellebene
• erweiterte Eigenschaften auf Modellebene

Nicht diesen Einzugsregeln folgen, wird ein Analysefehler generiert.

Leerzeichen

TMDL wendet standardmäßig die folgenden Regeln auf Leerzeichen innerhalb von Eigenschafts- und Ausdruckswerten an, wenn sie nicht in Backticks (```) oder doppelte Anführungszeichen (") eingeschlossen sind):

• Bei Eigenschaftswerten werden führende und nachfolgende Leerzeichen gekürzt.
• Bei Ausdrücken werden Leerzeichen am Ende von Ausdrücken gelöscht.
• Leerzeichenlinien werden auf leere Zeilen gekürzt (keine Leerzeichen/Tabstopps).

Gehäuse

Standardmäßig wird die TMDL-API für serialisieren/schreiben camelCaseverwendet, auf:

• Objekttypen
• Schlüsselwörter
• Enumerationswerte

Bei deserialize/read wird bei der TMDL-API die Groß-/Kleinschreibung nicht beachtet.

Verwandte Inhalte

Nachdem Sie nun ein Verständnis für TMDL haben, sehen Sie sich unbedingt Erste Schritte mit TMDL an, um zu erfahren, wie Sie eine TMDL-Modelldarstellung eines Power BI-Semantikmodells abrufen und bereitstellen.