create-pbi-report

Power BI レポートの作成

pbir CLI を使用して Power BI レポートを作成し、ひな形を生成します。uv tool install pbir-cli または pip install pbir-cli でインストールしてください。このスキルとあわせて、pbir-cli と pbi-report-design のスキルを読み込んでください。

曖昧または詳細が不十分なプロンプト

ユーザーのリクエストに具体的な指標、対象ユーザーの情報、構成の希望、書式の指定がない場合（例：「ダッシュボードを作って」「KPIを使って何か作って」）、作業を進める前に references/vague-prompts.md を参照してください。目的に合った質問をして、意図と仕様の隔たりを埋めてください。その後、ユーザーが指定できない、または指定しない項目には、妥当なデフォルト（sqlbi テーマ、エグゼクティブダッシュボードのパターン、モデルに基づく KPI の選定）を適用します。

ルール

• ビジュアル同士を重ねてはいけません
• 静的な書式設定では、ビジュアル単位の上書きよりテーマの変更を優先します
• 条件付き書式設定には、「bad」などのテーマカラーを使った拡張メジャーを優先します
• レポートは必ず名前付きのプロジェクトフォルダー内に作成します（例：sales-dashboard/Sales.Report）
• 変更のたびに pbir validate を実行します
• 新しいレポートには sqlbi テーマがすでに含まれています。ユーザーが別のテーマを明示的に求めない限り、pbir theme apply-template は実行しないでください
• 新しいレポートには、ページタイトル用の textbox ビジュアルが位置 (20,20)、高さ 90 で配置されたデフォルトの Page 1 がすでに含まれています。新しいテキストボックスを追加せず、代わりに pbir pages rename で既存のページ名を変更してください。タイトルのテキストボックスと重ならないよう、すべてのビジュアルを y:120 以降に配置してください。

クイックリファレンス

1. ユーザーからワークスペースとセマンティックモデルを確認します。Power BI Desktop への接続や、ソースデータを使ったレポートの作成を希望する場合は、まず Fabric または Power BI に公開済みのセマンティックモデルが必要であることを説明します。

2. ユーザーの要件を分析します。グラフ、フィルター、書式設定、分析など、不足している情報を検討します。不明な点があれば AskUserQuestion を使用します。

3. 設計概要（対象ユーザー、目的、意思決定に関する質問、ページごとの意図を含むページ一覧、確定したデザインの方向性、納品先）をまとめます。作成を始める前にユーザーの承認を得てください。references/design-brief.md を参照してください。

4. 不足しているセマンティックモデルのオブジェクトを検討します。ユーザーの依頼内容だけでなく、ビジュアルを充実させる比較対象（1 年前）、基準値（期間平均）、傾向の集計（14 日間の移動値）も考慮します。

5. プロジェクトフォルダーとレポートを作成します（デフォルトの形式は PBIP です）。

   mkdir -p /path/to/report-name
   cd /path/to/report-name
   pbir new report "Name.Report" -c "Workspace/Model.SemanticModel"
   

6. デフォルトのページ名を変更します（レポートに複数ページが必要な場合を除き、新しいページは追加しないでください）。pbir pages rename "Name.Report/Page 1.Page" --to "Overview" -f

7. ユーザーがカスタムテーマを求めた場合に限り、次を実行します。pbir theme apply-template "Name.Report" template-name（sqlbi テーマはデフォルトですでに含まれています）

8. モデルのフィールドを確認します。pbir model "Name.Report" -d

9. フィルターや書式設定に使うフィールド値をクエリします。pbir model "Name.Report" -q "EVALUATE VALUES('Table'[Column])"

10. フィールドのデータ型を確認します。pbir model "Name.Report" -d -t Table

11. ビジュアルを追加します（ページにはタイトル用のテキストボックスがすでにあります）。pbir add visual kpi "Name.Report/Overview.Page" --title "Revenue"

12. クエリの削減を設定します（スライサーと負荷の高いビジュアル）。references/interactivity.md を参照してください。

13. クロスフィルターの上書きとページナビゲーションを設定します。references/interactivity.md を参照してください。

14. フィルターとスライサーを追加し、スライサーの同期とリセットを設定します。references/interactivity.md を参照してください。

15. 検証します。pbir validate "Name.Report"

16. 公開します。pbir publish "Name.Report" "Workspace.Workspace/Name.Report"

17. 公開後に Fabric で開きます。pbir publish "Name.Report" "Workspace.Workspace/Name.Report" -o

18. または、Power BI Desktop でローカルに開きます。pbir open "Name.Report"

手順

ステップ 1：ビジネスプロセスを理解する

ビジュアルを作成する前に、セマンティックモデルを調べてドメインを理解します。pbir model "Report.Report" -d を使用して、テーブル、列、メジャー、階層を確認します。次の点を検討してください。

• このモデルはどのドメインを対象としていますか？（営業、財務、オペレーション、物流など）
• 最も重要な KPI とメジャーは何ですか？
• データをスライスするためのディメンションと階層は何ですか？
• どの時間粒度が適切ですか？（日次、週次、月次、四半期）

何かを構築する前に、AskUserQuestion を通じて具体的な提案を提示します。提案には、次の内容を含めてください。

• 表示する KPI カードと、それぞれに表示するメジャー
• 含めるトレンドチャートと、その時間粒度
• 最も有用なカテゴリ別の内訳
• 提供する詳細テーブル／マトリックスと、使用する階層
• フィルターでデータを絞り込む方法

実行前にデザインを調整してください。計画を修正するほうが、ビジュアルを作り直すよりも低コストです。

ステップ 1b：デザインブリーフをまとめて確定する

ステップ 1 の調査内容と、曖昧なプロンプトから得られた情報を、1 つのデザインブリーフにまとめます。これは要件を再度収集するためのものではありません。すでに判明している内容を単一の仕様として固定し、以降の構築手順でその仕様に従って作業できるようにします。ブリーフには、対象ユーザー、目的、閲覧者が答えるべき 2～5 個の判断に関する質問、各ページに 1 つの明確な意図を持たせたページ一覧、確定したデザインの方向性（トーンとシグネチャー）、および納品先を記載します。各項目の記入方法とコピー可能なテンプレートについては、references/design-brief.md を参照してください。

AskUserQuestion を通じてブリーフを一度提示し、「はい」または「X を変更」という明示的な承認を得ます。承認後はブリーフを確定済みとして扱い、構築手順ではスコープを再検討せず、それに従って進めます。後からスコープを変更する場合は、ビジュアルの方向性を暗黙のうちに変えるのではなく、ブリーフを再度開きます。

承認されたブリーフは pbi-report-design スキルに引き継がれます。このスキルがデザインの指針を管理します。デザインの方向性を確定し、各ページの意図を具体的なレイアウトに対応づけてから、以下の構築手順に進みます。デザインの方向性とページの意図からレイアウトへの対応は、概念として参照してください。この推論を担当するのは pbi-report-design です。ここで重複して説明しないでください。

ステップ 2：場所と接続先を特定する

レポートの作成場所と、接続するモデルを決定します。目的、対象ユーザー、判断に関する質問は確定済みのブリーフ（ステップ 1b）で合意されています。ここで再度確認しないでください。

pbir model                                       # List all known reports/models
pbir connect MyWorkspace MyReport                # Set active connection

ユーザーがワークスペースの場所を指定した場合は、プロジェクトフォルダー内にレポートをローカルで作成してから公開します。

ステップ 3：レポートを作成する

まずプロジェクトフォルダーを作成し、その中にレポートを作成します。デフォルトの形式は PBIP です。

mkdir -p sales-dashboard && cd sales-dashboard
pbir new report "Sales.Report" -c "MyWorkspace/Sales.SemanticModel"

作成される構造は次のとおりです。

sales-dashboard/
  Sales.Report/
    definition/
      pages/
      report.json
    StaticResources/
    definition.pbir
  Sales.pbip

ステップ 4：デフォルトページの名前を変更し、ページを追加する

レポートにはデフォルトの「ページ 1」が用意されており、ページタイトル用のテキストボックスもすでに含まれています。新しいページを作成するのではなく、名前を変更します。必要な場合にのみページを追加してください。

pbir pages rename "Sales.Report/Page 1.Page" --to "Overview" -f  # Rename default page
pbir add page "Sales.Report/Detail.Page" -n "Detail"              # Add extra pages only if needed
pbir pages active-page "Sales.Report" "Overview"

ステップ 5：テーマを設定する（ユーザーが要求した場合のみ）

sqlbi テーマはデフォルトで含まれています。ユーザーが別のテーマまたはカスタムカラーを明示的に求めた場合にのみ、テーマを変更してください。

# Only if user wants a different theme:
pbir theme apply-template "Sales.Report" custom-theme

# Or to customize specific colors:
pbir theme set-colors "Sales.Report" --good "#00B050" --bad "#FF0000"
pbir theme set-text-classes "Sales.Report" title --font-size 16
pbir theme set-formatting "Sales.Report" "card.*.border.radius" --value 8

ステップ 6：ページにビジュアルを追加する

まず実際のページ寸法を確認してください。1280x720 と決めつけないでください。pbir pages json "Report.Report/Page.Page" を使って確認します。オブジェクトモデルは、ビジュアルがページの境界内に収まっているか検証します。

意図的なビジュアルの階層構造でキャンバスを埋めます。1280x720 ページの標準的な構成は次のとおりです。

• 行 1（y: 20-160）：KPI ビジュアル -- 見出し指標を目標値と傾向線とともに表示する kpi ビジュアルを 2～3 個
• 行 2（y: 180-460）：傾向＋内訳 -- 折れ線／面グラフ（幅の約 60%）＋棒／縦棒グラフ（幅の約 40%）
• 行 3（y: 480-700）：詳細テーブル／マトリックス -- 階層と条件付き書式を備えた、幅いっぱいの tableEx または matrix

正確な座標、間隔の検証、ビジュアルコマンドを含むレイアウトの完全な例については、references/layout-example.md を参照してください。

主な原則：

• 間隔を統一する：(margin, gap, page_width, page_height) から位置を計算します。margin=24、gap=16 の 1280x720 の場合、使用可能な幅は 1232 です。ビジュアルを配置する前に計算を確認してください。
• タイトルの重複を避ける：ページタイトルは対象（「Order Lines」）、ビジュアルタイトルは区別する情報（「by Key Account」、「Monthly Trend」）にします。サブタイトルを非表示にします：pbir visuals subtitle "path" --no-show
• 並べ替え：グラフは最初のメジャーで降順に自動的に並べ替えられます。pbir visuals bind の後、並べ替えを明示的に設定します：pbir visuals sort "path" -f "Table.Measure" -d Descending

ユーザーが表示するメジャーやディメンションを選択するレポートでは、フィールドパラメーターを使って、ほぼ重複する N 個のビジュアルを 1 つにまとめます。references/interactivity.md（Field Parameters セクション）を参照してください。

ステップ 7：クエリ削減を設定する

スライサーを含むレポートや、マトリックス、マップ、高カーディナリティのテーブルがある混雑したページでは、作成時にクエリ削減を適用してください。後から適用すると、古いインタラクションペアが残り、意図しないクロスフィルターがすでにページに設定されている可能性があります。

3 つの構成要素（詳細は references/interactivity.md を参照）：

1. 各スライサーから負荷の高いビジュアルへの NoFilter visualInteractions ペアを追加します
2. フィルターペインの適用ボタンを有効にします：pbir filters pane-set
3. 各スライサーで適用ボタンを有効にします：各スライサーに対して pbir visuals format を実行します

クエリのコストが低い Import モードのレポートでは、適用前に、クロスハイライトを無効にすることで失われるインタラクティブ性に見合うかどうかを評価してください。

ステップ 8：インタラクションとナビゲーションを設定する

ビジュアルを配置した後、クロスフィルターのオーバーライドを設定し、ナビゲーションを構築します。既定ではすべてが相互にクロスフィルターするため、例外のみを設定してください。複数ページのレポートでは、個別のボタンではなく pageNavigator ビジュアルを追加します。

手順と注意点については、references/interactivity.md（Wiring Interactions and Navigation セクション）を参照してください。

ステップ 9：フィルターとスライサーを追加する

pbir add filter Date Year -r "Sales.Report" --values 2025
pbir add filter Geography Region -r "Sales.Report"
pbir add filter Products Category -p "Sales.Report/Detail.Page"

スライサーの種類の選択、同期グループ、フィルターのリセット／保持パターンについては、references/interactivity.md（Slicer Type, Sync, and Reset セクション）を参照してください。

ステップ 10：ビジュアルを書式設定する

書式設定の大半はテーマ（ステップ 5）で行います。個別の書式設定は、本当に一度限りのケースにのみ適用してください。

# Bulk formatting via glob (requires -f for glob patterns)
pbir set "Sales.Report/**/*.Visual.title.show" --value true -f
pbir set "Sales.Report/**/*.Visual.border.show" --value true -f

# Individual visual formatting
pbir visuals title "Sales.Report/Overview.Page/Revenue.Visual" --fontSize 14 --bold
pbir visuals background "Sales.Report/Overview.Page/Revenue.Visual" --color "#F8F9FA"

スライサーの選択に応じて変化するタイトルや、ステータスに応じて色が変わるタイトルには、_Report 拡張メジャーを使います。

# Author a selection-aware title measure
pbir dax measures add \
  "Sales.Report" \
  -n "Title_Sales" \
  -e "IF(ISFILTERED('Region'[Region]), \"Sales: \" & SELECTEDVALUE('Region'[Region], \"multiple regions\"), \"Sales: all regions\")" \
  -t _Report

# Bind via title CF, or drive a textbox text run with the measure

動的タイトルの主なルール：

• SELECTEDVALUE(..., "<fallback>") は必須です。指定しないと、複数選択時にタイトルが表示されなくなります
• テキストメジャーと色メジャーは分けてください（前者は文字列を返し、後者は「good」／「bad」などのテーマトークンを返します）。それぞれ個別にテストできます
• メジャーで制御するタイトルと固定のタイトルは併用できません。まず固定のタイトルをクリアしてください
• ISFILTERED／HASONEVALUE を使って選択なし／単一選択／複数選択の場合を推論してテストし、その後、レンダリングで確認してください

ステップ 11：検証する

pbir validate "Sales.Report"
pbir tree "Sales.Report" -v

ステップ 12：公開または開く

pbir publish "Sales.Report" "MyWorkspace.Workspace/Sales.Report"      # Publish
pbir publish "Sales.Report" "MyWorkspace.Workspace/Sales.Report" -o   # Publish and open in browser
pbir open "Sales.Report"                                               # Open in Power BI Desktop

よくあるレポートのパターン

エグゼクティブダッシュボード

• 上部にKPIカードを2～3枚配置（収益、注文数、利益率）
• トレンドを示す折れ線グラフ／面グラフを1つ配置（年次フィルターの場合は月次、月次の場合は日次／週次）
• 主要カテゴリ別の内訳を示すグラフ（棒グラフ／縦棒グラフ）を1～2つ配置
• 階層と条件付き書式を設定した詳細テーブルまたはマトリックスを1つ配置
• ページサイズ：1280x720（16:9）

詳細分析

• 上部にスライサーバーを配置（日付範囲、カテゴリフィルター）
• メインコンテンツとして、条件付き書式を設定した大きなテーブルまたはマトリックスを配置
• コンテキストを示す補助的なKPIカードを配置
• ページサイズ：1280x720または1920x1080

ツールヒントページ

• 小さいページ（320x240など）
• 焦点を絞ったビジュアルを2～3つ配置
• pbir pages type "path" --type tooltip で設定

参照ファイル

• references/vague-prompts.md -- 要件が不明確なプロンプトへの対応：的を絞った質問、妥当なデフォルト、構築前に提案するワークフロー
• references/design-brief.md -- 固定版デザインブリーフのテンプレート：意思決定のための質問、ページごとの意図、確定したデザインのアイデンティティ（トーンとシグネチャー）、納品先、承認ゲート、pbi-report-designへのルーティング
• references/layout-example.md -- 座標、間隔の検証、時間粒度のガイダンスを含む完全なレイアウト
• references/interactivity.md -- クエリの削減、クロスフィルターの接続、ナビゲーション、スライサーの種類／同期／リセット、フィールドパラメーター
• references/limitations.md -- ユーザーに伝えるエージェントの制限