refresh-semantic-model

セマンティックモデルの更新

Power BI Enhanced Refresh REST API と Fabric CLI を使用して、セマンティックモデルの更新をトリガー、監視、検証し、トラブルシューティングします。

基本概念

セマンティックモデルの更新では、アップストリームソースからデータを再読み込みしたり、依存オブジェクト（計算列、計算テーブル、メジャー）を再計算したりします。対象範囲はモデル全体、特定のテーブル、または個々のパーティションにできます。

REST API では 6 種類の更新を利用できます。7 番目の add は TMSL 専用です。

種類	データを再読み込み	再計算	主な用途	API
full	はい	はい	最初から完全に再読み込み	REST
automatic	条件付き	条件付き	スマート更新。必要な場合のみ処理	REST
dataOnly	はい	いいえ*	データを再読み込みし、依存オブジェクトをクリア	REST
calculate	いいえ	はい	データを再読み込みせずに再計算	REST
clearValues	いいえ	いいえ	オブジェクトのデータを空にする	REST
defragment	いいえ	いいえ	列のディクショナリをクリーンアップ	REST
add	追加	はい	パーティションに行を追加	TMSL

*dataOnly は依存オブジェクト（計算列、計算テーブル）をクリアしますが、再計算は行いません。復元するには、続けて calculate 更新を実行してください。

各種の詳しい説明、増分更新ポリシーでの動作、コミットモード、並列処理オプションについては、references/refresh-types.md を参照してください。

更新ワークフロー

ステップ 1：ID を解決する

API 呼び出しに必要なワークスペースとモデルの GUID を取得します。

WS_ID=$(fab get "WorkspaceName.Workspace" -q "id" | tr -d '"')
MODEL_ID=$(fab get "WorkspaceName.Workspace/ModelName.SemanticModel" -q "id" | tr -d '"')

ステップ 2：ベースラインデータを照会する（更新前の検証）

更新をトリガーする前に、データが実際に変更されたことを後で確認できるよう、ベースラインのスナップショットを取得します。モデルに対して DAX クエリを実行し、現在の行数または最大日付を取得します。

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX('FactSales'[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

出力を記録します。このベースラインを更新後の結果と比較して、新しいデータが到着したことを確認します。

ステップ 3：更新をトリガーする

モデル全体を更新する（最も簡単）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full"}'

特定のテーブルを更新する：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [{"table": "FactSales"}, {"table": "DimProduct"}]
  }'

特定のパーティションを更新する：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{
    "type": "full",
    "objects": [
      {"table": "FactSales", "partition": "FactSales_2024"},
      {"table": "FactSales", "partition": "FactSales_2023"}
    ]
  }'

データのみを更新する（再計算をスキップ）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"dataOnly","objects":[{"table":"FactSales"}]}'

計算のみを行う（データは再読み込みしない）：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

テーブルの値をクリアする：

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"clearValues","objects":[{"table":"StagingTable"}]}'

CLI 引数を使ったスクリプトベースの方法については、scripts/refresh_model.py を使用してください。

ステップ 4：ステータスを監視する

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

ステータスの値：Unknown、InProgress、Completed、Failed、Disabled、Cancelled

ステップ 5：更新後に検証する

更新が完了したら、ステップ 2 と同じ DAX クエリを再実行して比較します。

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/executeQueries" \
  -X post -i '{
    "queries": [{"query": "EVALUATE ROW(\"RowCount\", COUNTROWS(FactSales), \"MaxDate\", MAX('FactSales'[OrderDate]))"}],
    "serializerSettings": {"includeNulls": true}
  }'

更新が成功したのにデータが変わっていない場合：

• アップストリームのデータソースが更新されていません
• ETL パイプライン（Fabric パイプライン、ノートブック、Data Factory、その他のオーケストレーション）を先に実行する必要があります
• レイクハウス、ウェアハウス、SQL データベースを確認し、新しいデータが存在することを検証します
• Fabric レイクハウスの場合：fab run "Workspace.Workspace/Pipeline.DataPipeline" を実行するか、ノートブックをトリガーします
• 更新ではソースが提供するデータだけが取得されます。ソースが古いままの場合、更新は成功しても新しいデータは表示されません

ステップ 6：キャンセルする（必要な場合）

進行中の拡張更新をキャンセルするには、まず更新履歴から requestId を取得します。

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes?\$top=1"

応答には requestId フィールドが含まれます。これを使ってキャンセルします。

fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes/<requestId>" \
  -X delete

Enhanced API 経由でトリガーされた更新にのみ有効です（スケジュール更新やポータルからの更新には適用されません）。

更新スクリプトを使用する

scripts/refresh_model.py スクリプトは、CLI 引数を使って Enhanced Refresh API をラップします。

# Full refresh
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID

# Refresh specific tables
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --tables Sales,Calendar

# Refresh specific partitions
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --partitions Sales:Sales_2024

# Data-only then calculate (two-phase)
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t dataOnly --tables FactSales
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID -t calculate

# Partial batch with parallelism
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --commit partialBatch --parallelism 4

# Skip incremental refresh policy
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --no-policy

# Check status only
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --status-only

# Poll until complete
uv run scripts/refresh_model.py -w $WS_ID -m $MODEL_ID --poll

拡張更新オプション

拡張更新 API（Premium／Fabric 容量が必要）では、標準の更新に次の機能が追加されます。

パラメーター	デフォルト	目的
type	automatic	更新の種類（full、automatic、dataOnly、calculate など）
commitMode	transactional	アトミックなコミット、またはオブジェクトごとの部分バッチ
maxParallelism	10	並列処理スレッド数
retryCount	0	失敗時の自動再試行
objects	モデル全体	対象とするテーブル／パーティションの配列
applyRefreshPolicy	true	増分更新ポリシーを適用するか、スキップするか
effectiveDate	現在の日付	増分ポリシーの期間に使用する日付を上書き
timeout	05:00:00	試行ごとのタイムアウト（再試行を含む最大合計 24 時間）

よく使われるパターン

2 フェーズ更新（大規模モデル）

データの読み込みと再計算を分割し、制御性と障害の切り分けを向上させます。

1. すべてのテーブルを再読み込みするために、partialBatch を指定して dataOnly を実行します（各テーブルは個別にコミットされます）。
2. すべてをアトミックに再計算するために、transactional を指定して calculate を実行します。

選択したパーティションの更新

増分更新が設定されたテーブルでは、テーブル全体ではなく、特定の期間のパーティションだけを更新できます。パーティション名を確認するには、Tabular Editor、SSMS、または Fabric CLI によるエクスポートを使用して、XMLA エンドポイント経由でモデルの TMSL メタデータをクエリします。

fab export "Workspace.Workspace/Model.SemanticModel" -o /tmp/model -f

エクスポートした TMDL のテーブルファイルを確認します。各 partition ブロックには、パーティション名が記載されています。更新リクエストの objects 配列で、対象のパーティションを指定します。

ETL 後の更新

データパイプラインをオーケストレーションする場合：

1. 上流の ETL（Fabric パイプライン、ノートブック、ADF、またはカスタム ETL）を実行します。
2. ソース（レイクハウス、ウェアハウス、SQL）に最新データがあることを確認します。
3. セマンティックモデルの更新を開始します。
4. DAX クエリを使用して、行数または最大日付が変わったことを検証します。
5. 変わっていない場合は、ETL の出力を調査します。セマンティックモデルの更新は成功していますが、ソースのデータが古いままです。

トラブルシューティング

よくあるエラーのクイックリファレンスです。デバッグのワークフローと詳細なエラーテーブルを含むトラブルシューティングガイド全体は、references/troubleshooting.md をお読みください。

症状	考えられる原因	解決方法
資格情報エラーで失敗する	資格情報の期限切れ、未設定、またはコピー後に引き継がれていない	データセットの設定で更新します。fab cp で転送されるのは共有クラウド接続のみです
テーブルの型が一致しない	ソース列の型がモデル列の型と一致しない	モデル定義とソーススキーマの列のデータ型を確認し、パーティション式に Table.TransformColumnTypes を追加します
列が存在しない	ソース列の名前が変更または削除されている、あるいは大文字と小文字が異なる	ソーススキーマを確認し、パーティション式に Table.RenameColumns を追加します
タイムアウト（共有は 2 時間／Premium は 5 時間）	1 回の更新時間内にモデル全体を更新するには大きすぎる	増分更新を実装します。XMLA 経由でパーティション単位の更新を使用するか、モデルのサイズを縮小します
計算テーブルが空になる	dataOnly の更新ではクリアされますが、再構築されない	拡張更新 API 経由で calculate 更新を実行し、計算テーブルと計算グループを再構築します
Premium でスロットリングされる	同時実行中の更新が多すぎる	更新スケジュールをずらし、ピーク時を避けて更新します

テーブルごとの失敗のデバッグ

完全更新が失敗した場合は、Enhanced Refresh API を使って個々のテーブルを更新し、失敗しているテーブルを特定します。

# Refresh dimensions first
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Customers"}]}'

# Then facts
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"full","objects":[{"table":"Invoices"}]}'

# Then recalculate
fab api -A powerbi "groups/$WS_ID/datasets/$MODEL_ID/refreshes" \
  -X post -i '{"type":"calculate"}'

失敗しているテーブルのパーティション式を確認し、fab export または fab table schema を使って、ソーススキーマとモデルで想定されている列名や型を比較します。

大規模モデルの戦略

1 GB を超えるモデルや、更新に 1 時間以上かかるモデルには、対象を絞った方法が効果的です。

• パーティションレベルの更新：モデル全体ではなく、Enhanced REST API または XMLA エンドポイントを使って個々のテーブルパーティションを更新します。Premium／Fabric 容量が必要です。
• 増分更新：大規模なテーブルを日付で自動的にパーティション分割し、各サイクルでは最近のデータのみを更新します。Power Query で RangeStart／RangeEnd パラメーターを設定します。また、データ変更の検出にも対応しており、変更されていないパーティションを丸ごとスキップできます。
• 集計：大規模なファクトテーブルを、より粗い粒度でインポートモードの集計テーブルに事前集計します。詳細クエリは DirectQuery にフォールスルーします。更新時間とメモリ使用量の両方を削減します。
• ハイブリッドテーブル：履歴パーティションはインポートモードにし、最近のデータにはリアルタイムの DirectQuery パーティションを使用します。関連テーブルは Dual ストレージモードである必要があります。
• スケールアウト：Premium 容量でセマンティックモデルのスケールアウトを有効にし、更新とクエリのワークロードを分離します。プライマリが更新している間、読み取り専用レプリカがクエリを処理します。

容量の制限

容量タイプ	1 日あたりの最大更新回数	既定のタイムアウト	拡張機能
Pro	8	2 時間	いいえ
Premium Per User	48	5 時間	はい
Premium / Fabric	48	5 時間	はい

Pro 容量がサポートするのは、モデル全体の標準更新のみです。拡張更新機能（テーブル／パーティションの指定、コミットモード、並列処理、キャンセル、タイムアウトの上書き）には Premium または Fabric 容量が必要です。

要件

• ワークスペースの共同作成者以上の権限
• fab CLI で認証済みであること：fab auth login

追加リソース

参照ファイル

• references/refresh-types.md -- 7 種類すべての更新タイプ、コミットモード、並列処理、増分ポリシーとの相互作用、ステータス値、XMLA／TMSL の詳細、2 段階更新パターンを網羅した完全なリファレンス
• references/troubleshooting.md -- 資格情報エラー、型／スキーマの不一致、タイムアウト、容量制限、増分更新の問題、デバッグのワークフロー、大規模モデルの戦略を網羅した包括的なトラブルシューティングガイド

スクリプト

• scripts/refresh_model.py -- 拡張オプションをすべて指定して更新をトリガーし、監視するための CLI ツール

関連スキル

• semantic-model -- モデルの設計、構築、品質／パフォーマンスのレビュー
• lineage-analysis -- 下流レポートの検出と影響分析
• organize-semantic-model -- 整理と命名の修正
• fabric-cli（fabric-cli プラグイン）-- fab CLI を使ったワークスペースとアイテムの管理