tmdl-mastery

TMDL（Tabular Model Definition Language）をマスターする

概要

言語構文、フォルダー構造、オブジェクト型、式、シリアル化 API、CI/CD、デプロイに関する TMDL リファレンスです。TMDL は、互換性レベル 1200 以上の Power BI および Analysis Services のセマンティックモデル向けに、人が読みやすく、ソース管理に適した形式です。

2026 年のステータス概要

項目	ステータス（2026 年 4 月時点）
TMDL 言語の GA	2024 年 8 月から GA — プレビューではなくなりました
Power BI Desktop の TMDL ビュー	GA — セマンティックハイライト、オートコンプリート、コードアクション、差分プレビュー、互換性に関するプロンプト
既定の PBIP セマンティックモデル形式としての TMDL	既定 — model.bim は従来の BIM 形式です。新しい PBIP プロジェクトでは definition/*.tmdl ファイルが書き込まれます
Fabric Git 統合	セマンティックモデルを TMDL としてエクスポートします（TMSL/BIM ではありません）
TMSL / BIM	非推奨ではありません — XMLA スクリプトコマンドや JSON を必要とするツールで引き続きサポートされています。ソース管理には TMDL を、XMLA の createOrReplace コマンドのスクリプト作成には TMSL を使用してください
互換性レベル	1550 以上を推奨。一部の新しいプロパティ（formatStringDefinition、計算グループの複数選択／未選択の式など）には 1601 以上が必要です
Tabular Editor 2（無料）	TMDL の読み書きをサポート（2.17 以降）
Tabular Editor 3（有料）	DAX デバッガーとダイアグラムビューを備えたフル機能の TMDL IDE
VS Code TMDL 拡張機能	Microsoft の analysis-services.TMDL とコミュニティの CPIM.TMDL-language-support（DAX と M のハイライト、コードアクション、フォーマット、パンくずリスト）
Report Server	TMDL をサポートしていません — 従来の PBIX バイナリ形式を引き続き使用します

要点： ソース管理下に置く新しい Power BI / Fabric セマンティックモデルには TMDL を使用してください。XMLA スクリプトや model.bim が必要なツールには TMSL を引き続き使用してください。

TMDL と TMSL と BIM の比較

項目	TMDL（.tmdl フォルダー）	TMSL / BIM（model.bim）
形式	YAML に似たテキスト、インデントベース	単一の JSON ファイル
ファイル	テーブル、ロール、カルチャ、パースペクティブごとに 1 ファイル	1 つのモノリシックなファイル
Git との相性	優れています — 詳細な差分、マージの競合を最小限に抑制	劣ります — モデル全体が 1 つの差分になります
人間による読みやすさ	高い — 区切り文字が最小限で、DAX/M をそのまま記述	低い — JSON 文字列がエスケープされます
ツール	VS Code 拡張機能、Desktop の TMDL ビュー、Tabular Editor 3	任意の JSON エディター、Tabular Editor 2/3
API	TmdlSerializer（.NET）	JsonSerializer（.NET）、TMSL コマンド
移行	Tabular Editor または Desktop で BIM から変換できます	既定の従来形式

TMDL を使用する場合： 新規のソース管理対象プロジェクト、CI/CD プロジェクト、またはチームの PBIP プロジェクト全般。

TMSL/BIM を使用する場合： 従来のプロジェクト、Report Server（TMDL のサポートなし）、または BIM のみを受け付けるツール。

オブジェクト宣言の構文

TOM のオブジェクト型を名前の前に指定して、オブジェクトを宣言します。

model Model
    culture: en-US

table Sales

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

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

主なルール：

• 名前にドット、等号、コロン、シングルクォート、または空白が含まれる場合は、シングルクォートで囲みます
• 名前に含まれるシングルクォートは 2 つ重ねてエスケープします：'My ''Special'' Table'
• 子オブジェクトはインデントによって親の下に暗黙的にネストされます（コレクションの明示的な指定は不要です）
• 子オブジェクトを連続して記述する必要はありません — 列とメジャーは自由に交互に記述できます

プロパティの構文

プロパティにはコロンの区切り文字を使用し、式には等号の区切り文字を使用します。

column Category
    dataType: string          /// colon for non-expression properties
    sortByColumn: 'Cat Order' /// colon for object references
    isHidden                  /// boolean shortcut (true implied)
    isAvailableInMdx: false   /// explicit boolean

measure Total = SUM(Sales[Amount])   /// equals for default expression
    formatString: $ #,##0            /// colon for properties after expression

テキストプロパティ値： 先頭と末尾の二重引用符は省略可能で、自動的に削除されます。値に先頭または末尾の空白が含まれる場合は必須です。内部の二重引用符は 2 つ重ねてエスケープします。

オブジェクトの種類ごとの既定プロパティ

オブジェクトの種類	既定プロパティ	言語
measure	Expression	DAX
calculatedColumn	Expression	DAX
calculationItem	Expression	DAX
partition (M)	Expression	M
partition (calculated)	Expression	DAX
tablePermission	FilterExpression	DAX
namedExpression	Expression	M
annotation	Value	Text
jsonExtendedProperty	Value	JSON

既定のプロパティでは、同じ行、または次の行以降の複数行の式として等号（=）を使用します。

式 -- 単一行と複数行

/// Single-line expression
measure 'Sales Amount' = SUM(Sales[Amount])

/// Multi-line expression (indented one level deeper than parent properties)
measure 'YoY Growth %' =
        VAR CurrentSales = [Sales Amount]
        VAR PYSales = CALCULATE([Sales Amount], SAMEPERIODLASTYEAR('Date'[Date]))
        RETURN DIVIDE(CurrentSales - PYSales, PYSales)
    formatString: 0.00%

/// Triple-backtick block for verbatim content (preserves whitespace exactly)
partition 'Sales-Part' = m
    mode: import
    source = ```
        let
            Source = Sql.Database("server", "db"),
            Sales = Source{[Schema="dbo",Item="Sales"]}[Data]
        in
            Sales
        ```

式のルール：

• 複数行の式は、親プロパティより1段深くインデントします
• トリプルバッククォートのブロックを使用しない限り、末尾の空白は削除されます
• トリプルバッククォートのブロックでは空白が保持され、終了デリミターが左端の境界を設定します

説明（/// 構文）

/// This table contains all sales transactions
/// Updated daily via incremental refresh
table Sales

    /// Total revenue across all product lines
    measure 'Sales Amount' = SUM(Sales[Amount])

オブジェクトの上にあるトリプルスラッシュコメントは、そのオブジェクトの TOM Description プロパティになります。説明ブロックとオブジェクト型のキーワードの間に空白を入れないでください。

Ref キーワード

別の TMDL オブジェクトを参照するか、コレクションの順序を定義します。

/// In model.tmdl -- defines table ordering for deterministic roundtrips
model Model
    culture: en-US

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

ref culture en-US
ref culture pt-PT

ref role 'Regional Manager'

ルール： ファイルが見つからない参照先オブジェクトは、逆シリアル化時に無視されます。ファイルは存在するものの ref がないオブジェクトは、コレクションの末尾に追加されます。

TMDL フォルダー構造

definition/
  database.tmdl           # Database properties (compatibilityLevel, etc.)
  model.tmdl              # Model properties, ref declarations
  relationships.tmdl      # All relationships
  expressions.tmdl        # Shared/named expressions (Power Query parameters)
  functions.tmdl          # DAX user-defined functions
  dataSources.tmdl        # Legacy data sources
  tables/
    Sales.tmdl            # Table + all its columns, measures, partitions, hierarchies
    Product.tmdl
    Calendar.tmdl
  roles/
    RegionalManager.tmdl  # Role definition with permissions and members
    Admin.tmdl
  cultures/
    en-US.tmdl            # Translations for all objects in this culture
    pt-PT.tmdl
  perspectives/
    SalesView.tmdl        # Perspective definition

テーブル、ロール、カルチャ、パースペクティブごとに1つのファイルを使用します。内部メタデータ（列、メジャー、パーティション、階層）はすべて親テーブルのファイル内に格納されます。

TMDL スクリプト（createOrReplace）

Power BI Desktop の TMDL ビューを使用して、ライブのセマンティックモデルに変更を適用します。

createOrReplace

    table 'Time Intelligence'
        calculationGroup
            precedence: 1

        calculationItem Current = SELECTEDMEASURE()

        calculationItem YTD =
                CALCULATE(SELECTEDMEASURE(), DATESYTD('Calendar'[Date]))

        calculationItem PY =
                CALCULATE(SELECTEDMEASURE(), SAMEPERIODLASTYEAR('Calendar'[Date]))

        column 'Time Calc'
            dataType: string
            sourceColumn: Name
            sortByColumn: Ordinal

        column Ordinal
            dataType: int64
            sourceColumn: Ordinal
            summarizeBy: none

スクリプトの実行ごとに、コマンド動詞は1つだけ使用できます。createOrReplace コマンドは、指定されたオブジェクトとそのすべての子孫を作成または置換します。

インデントのルール

TMDL では厳密な空白インデントが使用され、既定では各レベルに タブを1つ使用します。

• レベル 1： オブジェクト宣言（table、measure、column）
• レベル 2： オブジェクトのプロパティ（dataType、formatString）
• レベル 3： 複数行の式（DAX/M コード）

データベースレベルおよびモデルレベルの直接の子（table、relationship、role、culture、perspective、expression）は、ルートの下に暗黙的に配置されるため、インデントは不要です。インデントが正しくない場合は、TmdlFormatException が発生します。

大文字と小文字、および空白

• シリアル化では、オブジェクトの種類、キーワード、列挙値に camelCase を使用します
• 逆シリアル化では、大文字と小文字を区別しません
• プロパティ値の先頭と末尾の空白はトリミングされます
• 式の末尾にある空行は削除されます
• 式内の空白のみの行は、空行として保持されます

TMDL シリアル化 API（.NET）

using Microsoft.AnalysisServices.Tabular;

// Serialize model to TMDL folder
TmdlSerializer.SerializeDatabaseToFolder(database, @"C:\output\model-tmdl");

// Deserialize TMDL folder back to TOM
var db = TmdlSerializer.DeserializeDatabaseFromFolder(@"C:\output\model-tmdl");

// Serialize single object to string
string tmdl = TmdlSerializer.SerializeObject(table.Measures["Total Sales"]);

NuGet パッケージ： Microsoft.AnalysisServices.NetCore.retail.amd64（または同等の .NET Framework パッケージ）

エラーの種類： TmdlFormatException（無効な構文）および TmdlSerializationException（構文は有効だが、TOM メタデータが無効）。どちらにも Document、Line、LineText プロパティが含まれます。

自己検証

生成した TMDL をデプロイする前に、必ず powerbi-master:validation-testing スキルの4層の検証パイプラインを実行してください。

1. 構文 -- TmdlSerializer.DeserializeDatabaseFromFolder により、TmdlFormatException（不正なインデント、無効なキーワード）を検出します
2. メタデータ -- 同じ呼び出しで TmdlSerializationException（無効なプロパティの組み合わせ）を検出し、model.Validate() で参照切れを検出します
3. ベストプラクティス -- Tabular Editor 2 CLI の -A スイッチ、または semantic-link-labs.run_model_bpa により、標準の Microsoft BPA ルールセットを実行します
4. リネージ -- model.Validate().Errors とカスタムの Tabular Editor C# スクリプトにより、sortByColumn や measure-references-column の問題を検出します

validation-testing スキルには、各層ですぐに実行できる手順（C#、Python、GitHub Actions YAML）が用意されています。デプロイを推奨する前に、必ず検証してください。

Power BI Desktop の TMDL ビュー（2026）

TMDL ビューは、セマンティックモデルの変更をスクリプト化するための、Power BI Desktop に統合されたコードエディターです。2026 年のリリース ウェーブ時点で、次の機能が含まれています。

• セマンティックな強調表示、オートコンプリート（Ctrl+Space）、ホバー時のツールチップ、コード アクション（リネージ タグの生成、プロパティ名の誤記修正）
• コードの書式設定。Shift+Alt+F またはリボンの［書式設定］ボタンを使用します（コンテキスト メニューの［選択範囲の書式設定］を含む）
• 専用の［問題］ペインを使用したエラー診断
• 差分のプレビュー -- スクリプトの実行前後のモデルの TMDL 差分を横並びまたはインラインで表示し、ツールバーから移動できます（プレビューできるのは有効な TMDL の実行のみです）
• 互換性レベルのアップグレード プロンプト -- スクリプトで現在のモデルの互換性レベルを超えるプロパティ（たとえば、formatStringDefinition の場合は 1550 -> 1601）が使われていると、Desktop により自動アップグレードが促されます
• 複数タブのスクリプト。PBIP プロジェクトの TMDLScripts/ フォルダーに保存されます（タブごとに 1 ファイル）
• データペインからエディターにオブジェクトをドラッグすると、createOrReplace としてスクリプト化されます。ドラッグする前に Ctrl キーを押すと複数選択できます
• 右クリックして、［TMDL のスクリプト化］を選択すると、新しいタブまたはクリップボードに出力できます
• ［適用］ボタンでメタデータのみの変更が適用されます（データ更新は行われません）。TMDL で列名を変更すると、列は sourceColumn から切り離されます（Power Query エディターには引き続きソース名が表示されます）
• 正規表現による検索と置換での一括名前変更 -- プレフィックス（fact_、dim_）の削除や大文字と小文字の変更によく使われるパターンです

制限事項： Desktop は、外部で変更された TMDL ファイルをホットリロードしません。VS Code で .tmdl ファイルを編集した後は、変更を反映するために Power BI Desktop を再起動してください。

Semantic Link Labs（Fabric ノートブックからの Python TOM）

.NET ツールチェーンを使わずに Python からセマンティックモデルをスクリプト化するには、Fabric ノートブック内で semantic-link-labs（PyPI：semantic-link-labs）を使用します。TOM の Python 向けラッパーを提供します。

%pip install semantic-link-labs -q

import sempy_labs as labs
from sempy_labs.tom import connect_semantic_model

with connect_semantic_model(dataset="SalesModel", workspace="Sales-Dev", readonly=False) as tom:
    # Add a measure
    tom.add_measure(
        table_name="Sales",
        measure_name="Sales Amount",
        expression="SUM(Sales[Amount])",
        format_string="$ #,##0.00",
        display_folder="Revenue",
    )

    # Add an incremental refresh policy
    tom.add_incremental_refresh_policy(
        table_name="Sales",
        column_name="OrderDate",
        start_date="2020-01-01T00:00:00",
        end_date="2025-12-31T00:00:00",
        incremental_granularity="Day",
        incremental_periods=30,
        rolling_window_granularity="Month",
        rolling_window_periods=36,
    )

    # tom.save_changes() is called automatically on context exit

詳細なクックブックについては、references/tmdl-programmatic-python.md を参照してください。

追加リソース

参考ファイル

• references/tmdl-syntax-reference.md -- すべてのオブジェクト タイプ、プロパティ、式のルールを網羅した TMDL 構文および文法の完全なリファレンス
• references/tmdl-examples-cookbook.md -- テーブル、列、メジャー、パーティション、リレーションシップ、ロール、パースペクティブ、カルチャ、計算グループ、階層、KPI、注釈、フィールド パラメーターなど、あらゆるオブジェクト タイプのコピーして使える TMDL の例
• references/tmdl-cicd-patterns.md -- CI/CD パイプライン、Git 統合、デプロイ パターン、Tabular Editor CLI、Azure DevOps と GitHub Actions のワークフロー、マージ競合への対処方法
• references/tmdl-programmatic-python.md -- Fabric Python ノートブックからの semantic-link-labs / SemPy TOM スクリプト：メジャー、計算グループ、増分更新、RLS、Direct Lake、BPA、モデルのエクスポート パターン

関連スキル

• powerbi-master:validation-testing -- デプロイ前に TMDL アーティファクトを検証します。TmdlSerializer パーサー、TOM Validate、Tabular Editor CLI / semantic-link-labs による BPA、カスタム C# ルール スクリプトを使用します

Microsoft Learn の公式リファレンス（2026）

• TMDL の一般提供開始のお知らせ -- TMDL の GA 発表
• Power BI Desktop で TMDL ビューを使用する -- シナリオを含む機能の概要
• Power BI Desktop プロジェクトのセマンティック モデル フォルダー -- PBIP 内の TMDL
• TMDL スクリプトのリファレンス（Microsoft Learn） -- createOrReplace コマンドのドキュメント