semantic-model

セマンティックモデル：設計、構築、更新、レビュー

ターミナルから Power BI／Analysis Services のテーブルモデルを設計、構築、更新、レビューするためのガイダンスです。モデルのレビューとモデリングのベストプラクティスを統合し、あらゆる変更を対応可能な最も限定的なツールに振り分けます。詳細は references/ にあり、このファイルでは運用ループと振り分けについて説明します。

使用する場面

• モデルを設計または構築する場合：スタースキーマ、リレーションシップ、メジャー、計算グループ、ロール、パラメーター、ストレージモード、増分更新
• モデルを最適化する場合：サイズ／VertiPaq、DAX の正確性、Direct Lake、更新コスト
• 品質、パフォーマンス、ベストプラクティスの基準に照らしてモデルをレビューまたは監査する場合
• Copilot／AI で利用するモデルを準備する場合

使用しない場面

• レポートのビジュアル、ページ、書式を編集する場合：pbir-cli スキル（reports プラグイン）を使用します
• 個別の DAX クエリのパフォーマンスをチューニングする場合：dax スキルを使用します
• TMDL ファイルの構文を扱う場合：tmdl スキルを使用します（このスキルではファイル編集のフォールバック先として案内します）
• te コマンド自体を扱う場合：コマンドリファレンスには te-cli スキル（tabular-editor プラグイン）を使用します。このスキルでは、その上位にあるモデリングの判断を扱います

ツールのカスケード（運用の基本ルール）

対応可能な最も限定的なツールから、順番に使用します。ほとんどの編集はステップ 1 で完了します。

1. まず te CLI を使用します。 操作ごとに動詞を 1 つ使用し、--save まではメモリ上にステージングします。保存時には DAX と参照整合性のゲートが実行されます。メジャー、列、リレーションシップ（te add での Sales[K]->Dim[K] 省略記法）、ロールと RLS フィルター、計算グループ／項目、DAX の書式設定（モデル全体には te set <path> --format Expression、または te script --inline "Model.AllMeasures.FormatDax();"）、te bpa、te vertipaq、te query の追加／設定／削除／移動に対応しています。Bash の呼び出しごとに新しいシェルが起動するため、各コマンドに --model <path>（リモートの場合は -s／-d）を渡すか、TE_SESSION を設定してください。プロパティは -p Name=Value で指定します。まず te get <obj> --properties で、実際のオブジェクトで設定可能なプロパティを確認してください。すべての変更は --save するまでドライランです。コマンドリファレンス全体は te-cli スキルを参照してください。
2. te でプロパティにアクセスできない場合は、TOM またはモデル MCP を使用します。 一部のプロパティは te set -p にありません（例：alternateOf、securityFilteringBehavior、crossFilteringBehavior、KPI のサブオブジェクト、言語スキーマの内容、カレンダーオブジェクト）。これらは te script による C# パス（プロセス内の TOM）、または connect-pbid スキル（ライブのローカル Desktop インスタンスに対する PowerShell + TOM／ADOMD。トレースへの唯一の経路でもあり、EVALUATEANDLOG、集計ヒットイベント、ストレージ DMV に対応）を通じて操作します。MCP を使用する場合は、Power BI Modeling MCP サーバーも利用できます。ローカル Desktop プロキシは Direct Lake にアクセスできません。Direct Lake の場合はリモート XMLA エンドポイントを使用してください。
3. 最後に fab と直接の TMDL 操作を行う場合は、tmdl スキルを使用します。 モデル編集用の動詞がない、サービスまたはファイル形状の操作が対象です。たとえば、ロールへの Entra プリンシパルの割り当て（.tmdl ではなくワークスペース側で行う）、レポートとモデルのバインド、Copilot フォルダーの機能（AI の指示、AI データスキーマ、検証済みの回答）、Direct Lake の背後にある Lakehouse／Delta の再構成、または N 回の te 呼び出しより 1 つの TMDL 差分で行う方が明確な大規模な構造変更です。AI の指示／スキーマを Fabric から読み取り専用で取得するには、scripts/get_semantic_model_ai_metadata.py を使用してください。tmdl スキルで TMDL を作成し、その後 te validate を実行してください。

順序のゲート：RELATED() またはテーブル間の CALCULATE() を使用するメジャーを追加する前に、リレーションシップを追加してください。そうしないと、保存時のゲートで DAX0002（コンテキストにリレーションシップがありません）が発生します。

DAX とメタデータにおけるオブジェクト参照

列参照は'Table'[Column]の形式で記述します。テーブル名は必ず含め、必ずシングルクォートで囲みます。メジャー参照は[Measure]の形式で記述し、テーブル名を前に付けてはいけません。このルールは、メジャー、計算列、計算項目の式、RLS フィルター、書式文字列の式、DAX クエリ（te query、pbir model -q）、およびオブジェクトについて言及する説明や注釈など、DAX やモデルのメタデータでオブジェクト名を指定するあらゆる場面に適用されます。

理由：メジャーはホームテーブルではなくモデルに属するため、テーブル間で移動しても、それを使用する式は変更されません。また、[Measure]と記述すれば、それが列ではなくメジャーだと一目でわかります。テーブル名の修飾がない列は、同じ列名を持つテーブルが2つあるだけで曖昧になります。すべてのテーブル名を引用符で囲むことで、名前に引用符が必要かどうかにかかわらず、表記を統一できます。

ライフサイクル

設計

ディメンションモデルを採用します。ファクトと共通ディメンションで構成するスター型は、スノーフレーク型やファクト間結合よりも適しています。構築を始める前にストレージモードと更新戦略を決めてください。公開後は、どちらもほぼ取り消せません。references/dimensional-modeling.md、references/storage-modes.md、references/composite-models.md、references/direct-lake.mdを参照してください。

構築

上記の一連の手順に沿って、変更を1つずつ行います。メジャーは、完全なメタデータ（DisplayFolder、FormatString、Description）を含めて一度に作成します。変更のたびに検証を実行し（te validate）、BPA（te bpa run --fail-on error）を必須チェックとして実行します。オブジェクトの名前変更や移動は、下流のレポートやモデルを予期せず破損させる場合があります。まずリネージチェックを実行し、その後pbir-cli／fabric-cliで反映してください（references/refactoring-renaming.mdを参照）。各領域の詳細なガイダンス：references/relationships.md、references/time-intelligence.md、references/calculation-groups.md、references/parameters.md、references/security.md、references/dax-authoring.md。

更新

ターミナルから増分更新を設定します（te incremental-refresh）。Direct Lake では、更新がフレーミングとなります。references/incremental-refresh.mdと、監視およびトラブルシューティングについてはrefresh-semantic-modelスキルを参照してください。

レビュー

以下のカテゴリに照らして監査し、ファイルの場所を示した優先順位付きの指摘事項を作成します。まずscripts/get_model_info.pyでコンテキスト（ストレージモード、サイズ、接続されたレポート、認定状況、データソース、更新スケジュール）を収集します。完全なチェックリストはreferences/review-checklist.md、パフォーマンスの手法はreferences/performance.mdを参照してください。

レビューカテゴリ（深刻度順）

• 重大：双方向の曖昧さ、循環依存関係、データ型の欠落、孤立したテーブル、フェイルオープンのRLS、行を暗黙のうちに除外する制限付きリレーションシップ
• メモリとサイズ：カーディナリティの高いディクショナリ、自動属性階層（非表示列／カーディナリティの高い列のisAvailableInMDX）、分割されていないDateTime、自動日付／時刻テーブル、誤ったデータ型、メジャーにすべき計算列、未使用オブジェクト
• データの削減：フィルターされていないファクトの履歴（増分更新なし）、不要な列、レポートに不要な詳細粒度、上流で処理する方が適切なロジック
• DAX の正確性：CALCULATEで列ではなくテーブルをフィルターすること、ガードのない除算、コンテキストを考慮しない計算列、変数による時間シフトのバグ（references/dax-authoring.md。クエリのチューニングにはdaxスキルを使用）
• メジャーの適正管理：暗黙的なメジャー、モデルに属するレポートスコープのメジャー、曖昧な重複
• ドキュメントとAI：説明の欠落（Copilotは200文字を超えると切り詰めます）、表示フォルダーの欠落、同義語の欠落、一貫性のない命名（organize-semantic-modelを使用）
• 設計：スター スキーマの違反、日付テーブルの誤ったマーク、多対多リレーションシップにブリッジがないこと、使用されていない非アクティブなリレーションシップ
• Direct Lake：1側のキーが一意でないこと（クエリが実行時に失敗）、DirectQueryへのフォールバック、Direct Lakeの種類ごとの計算列サポート、Deltaのガードレール違反

関連スキル

• tmdl：TMDL ファイルの作成（カスケードのステップ 3 のフォールバック）
• dax：DAX クエリのパフォーマンス最適化
• connect-pbid：稼働中の Desktop インスタンスに対する PowerShell 経由の TOM / ADOMD、トレース、TOM / MCP 層
• te-cli：te コマンドのリファレンス
• c-sharp-scripting：te ではアクセスできないプロパティ向けの TOM C# スクリプトとマクロ（te script）
• organize-semantic-model：整理と命名の修正
• refresh-semantic-model：更新の監視とトラブルシューティング
• lineage-analysis：アーティファクトのリネージ（ワークスペースをまたいで、このモデルを利用する下流のレポートとモデル）。モデル内のオブジェクト依存関係とは別のものです
• bpa-rules（tabular-editor）：BPA ルールの作成、fabric-cli：サービス／ワークスペースの操作

リファレンスマップ

references/dimensional-modeling.md:    star schema, SCD2, junk / degenerate dimensions, header-detail, bridges
references/relationships.md:           cardinality, limited relationships, ambiguity, active / inactive, USERELATIONSHIP
references/time-intelligence.md:       classic vs calendar TI, mark-as-date traps, week-based / 4-4-5
references/calculation-groups.md:      precedence, sideways recursion, selection expressions, the variant trap
references/parameters.md:              field parameters, what-if parameters, dynamic titles
references/security.md:                RLS validation + defensive filters, bidirectional + RLS, OLS restrictions
references/query-semantic-model.md:    querying a model with DAX, INFO functions, output formats, probing
references/storage-modes.md:           Import / DirectQuery / Dual / Hybrid decision matrix
references/composite-models.md:        source groups, regular vs limited, Direct-Lake-plus-Import
references/aggregations.md:            user-defined aggregations, grain, te-script AlternateOf
references/direct-lake.md:             OneLake vs SQL, framing, DirectQuery fallback, guardrails
references/incremental-refresh.md:     IR policy, detect data changes, hybrid / real-time, refresh strategy
references/vertipaq-optimization.md:   VPA metrics, value vs hash encoding, splitting high-cardinality keys
references/dax-authoring.md:           variable semantics, DIVIDE, measure vs calc column (gaps vs the dax skill)
references/ai-copilot-readiness.md:    the Copilot grounding contract, synonyms / linguistic schema, descriptions, Q&A retirement
references/metadata-and-organization.md: descriptions, display folders, naming, measure tables, perspectives
references/hierarchies-cultures.md:    user hierarchies, parent-child, KPIs, perspectives, cultures / translations
references/documentation-and-bpa.md:    data dictionary, BPA documentation gate, metadata diffs, intra-model impact analysis (artifact lineage = the lineage-analysis skill)
references/refactoring-renaming.md:    safe rename workflow (lineage check first, then propagate via pbir-cli / fabric-cli)
references/review-checklist.md:        full audit checklist with remediation
references/performance.md:             performance testing, unused-column detection, memory analysis
scripts/get_model_info.py:             model metadata overview (mode, size, reports, endorsement, sources, refresh)
scripts/manage-ai-metadata.csx:        read/write AI instructions and AI schema through TOM culture linguistic metadata
scripts/get_semantic_model_ai_metadata.py: Fabric CLI service-definition readback for AI instructions and AI schema

このスキルで意図的に扱わないこと

• GUI ツールの使い方と、旧レビュー スキルの「利用可能なツールを何でも使う」という方針：te-cli を優先するカスケードに置き換えられています
• 手作業で作成する Q&A の表現：Q&A は廃止予定であり、Copilot は表現を読み取らないため、同義語と説明の整備に注力してください
• セキュリティとして提示されるパースペクティブや表示フォルダー：どちらもモデルへのアクセス権があれば誰でもクエリできます。RLS / OLS を使用してください
• PBIT 形式：対象外です