# 帳票設計書 8-Export-DbaExecutionPlan

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbaExecutionPlanコマンドレットに関する帳票設計書です。プランキャッシュから実行計画を抽出し、.sqlplanファイルとして保存する機能について記載しています。

### 本帳票の処理概要

Export-DbaExecutionPlanは、SQL Serverのプランキャッシュに対してDMVを使用してクエリを実行し、実行計画をXMLファイル（.sqlplan拡張子）としてエクスポートするコマンドレットです。生成されたファイルはSQL Server Management Studio（SSMS）で直接開いて詳細な分析が可能です。

**業務上の目的・背景**：クエリパフォーマンスの分析において、実行計画の確認は重要な診断手段です。プランキャッシュからの実行計画抽出により、クエリ実行時にキャプチャする手間を省き、パフォーマンスパターンの分析や最適化機会の特定が容易になります。

**帳票の利用シーン**：
1. クエリパフォーマンス問題のトラブルシューティング
2. インデックスチューニングのための実行計画分析
3. 特定期間のクエリパフォーマンストレンド分析
4. ベンダーサポートへの診断情報提供
5. パフォーマンス監査・レビュー用の資料作成

**主要な出力内容**：
1. 単一ステートメント実行計画ファイル（.sqlplan）
2. バッチクエリ実行計画ファイル（-batch.sqlplan）
3. エクスポートサマリー情報（PSCustomObject）

**帳票の出力タイミング**：Export-DbaExecutionPlanコマンドを実行した時点で、指定ディレクトリに.sqlplanファイルが生成されます。

**帳票の利用者**：データベース管理者（DBA）、パフォーマンスエンジニア、SQLチューニング担当者

## 帳票種別

実行計画ファイル（XML / .sqlplan）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbaExecutionPlanコマンド実行 |
| N/A | SSMS | ファイル > 開く | .sqlplanファイル表示 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | XML (.sqlplan) |
| 用紙サイズ | N/A（XMLファイル） |
| 向き | N/A |
| ファイル名 | {Instance}-{Database}-{Position}-{SqlHandle}.sqlplan |
| 出力方法 | ディレクトリへのファイル書き込み |
| 文字コード | UTF-8（XML標準） |

### ファイル命名規則

| ファイル種別 | 命名パターン | 例 |
|------------|-------------|---|
| 単一ステートメント | {Instance}-{DB}-{Position}-{SqlHandle}.sqlplan | SQL01-AdventureWorks-1-0A1B2C3D.sqlplan |
| バッチクエリ | {Instance}-{DB}-{Position}-{SqlHandle}-batch.sqlplan | SQL01-AdventureWorks-1-0A1B2C3D-batch.sqlplan |

## 帳票レイアウト

### レイアウト概要

.sqlplanファイルはXML形式の実行計画データを含みます。

```
┌─────────────────────────────────────┐
│    XML宣言                          │
│  <?xml version="1.0"...>           │
├─────────────────────────────────────┤
│    ShowPlanXML要素                  │
│      └─ BatchSequence              │
│           └─ Batch                 │
│                └─ Statements       │
│                     └─ StmtSimple  │
│                          └─ QueryPlan│
│                               └─ RelOp│
│                                    ...│
└─────────────────────────────────────┘
```

### 出力オブジェクト

Export-DbaExecutionPlanは各実行計画についてPSCustomObjectを返します。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ComputerName | コンピュータ名 | Server.ComputerName | 文字列 |
| 2 | InstanceName | インスタンス名 | Server.ServiceName | 文字列 |
| 3 | SqlInstance | 完全インスタンス名 | Server.DomainInstanceName | 文字列 |
| 4 | DatabaseName | データベース名 | DMV結果 | 文字列 |
| 5 | SqlHandle | SQLハンドル（16進数） | sys.dm_exec_query_stats | 文字列 |
| 6 | CreationTime | プラン作成日時 | sys.dm_exec_query_stats | DateTime |
| 7 | LastExecutionTime | 最終実行日時 | sys.dm_exec_query_stats | DateTime |
| 8 | OutputFile | 出力ファイルパス | 処理結果 | 文字列 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes（パイプライン時はNo） |
| Database | 対象データベース | No |
| ExcludeDatabase | 除外データベース | No |
| SinceCreation | 作成日時フィルタ | No |
| SinceLastExecution | 最終実行日時フィルタ | No |
| Path | 出力ディレクトリ | No（デフォルト: DbatoolsExportパス） |
| InputObject | パイプライン入力 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | Statement_Start_offset | 昇順（ROW_NUMBER） |

### 改ページ条件

ファイルベースのため改ページは適用されません。

## データベース参照仕様

### 参照テーブル一覧

| DMV/関数 | 用途 | 結合条件 |
|----------|------|---------|
| sys.dm_exec_query_stats | 実行統計取得 | CROSS APPLY |
| sys.dm_exec_text_query_plan | 単一ステートメントプラン | plan_handle, offsets |
| sys.dm_exec_query_plan | バッチクエリプラン | plan_handle |
| sys.dm_exec_sql_text | SQLテキスト | plan_handle |

### 使用クエリ

```sql
SELECT DB_NAME(deqp.dbid) AS DatabaseName,
       OBJECT_NAME(deqp.objectid) AS ObjectName,
       detqp.query_plan AS SingleStatementPlan,
       deqp.query_plan AS BatchQueryPlan,
       ROW_NUMBER() OVER (ORDER BY Statement_Start_offset) AS QueryPosition,
       sql_handle AS SqlHandle,
       plan_handle AS PlanHandle,
       creation_time AS CreationTime,
       last_execution_time AS LastExecutionTime
FROM sys.dm_exec_query_stats deqs
CROSS APPLY sys.dm_exec_text_query_plan(deqs.plan_handle,
            deqs.statement_start_offset,
            deqs.statement_end_offset) AS detqp
CROSS APPLY sys.dm_exec_query_plan(deqs.plan_handle) AS deqp
CROSS APPLY sys.dm_exec_sql_text(deqs.plan_handle) AS execText
[WHERE conditions]
```

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| SqlHandle | 0x + バイト配列の16進変換 | N/A | PadLeft(2, "0") |
| QueryPosition | ROW_NUMBER() OVER (ORDER BY Statement_Start_offset) | N/A | ステートメント位置 |
| shortName | インスタンス + DB + Position + SqlHandle短縮版 | N/A | ファイル名生成用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaExecutionPlan実行] --> B{入力判定}
    B -->|InputObject| C[Export-Plan関数呼び出し]
    B -->|SqlInstance| D[Connect-DbaInstance]
    D --> E[WHERE条件構築]
    E --> F{Database?}
    F -->|Yes| G[DB IN条件追加]
    F -->|No| H{SinceCreation?}
    G --> H
    H -->|Yes| I[creation_time条件追加]
    H -->|No| J{SinceLastExecution?}
    I --> J
    J -->|Yes| K[last_execution_time条件追加]
    J -->|No| L{ExcludeDatabase?}
    K --> L
    L -->|Yes| M[DB NOT IN条件追加]
    L -->|No| N[クエリ実行]
    M --> N
    N --> O[結果行処理]
    O --> P[Export-Plan関数呼び出し]
    P --> Q[バッチプラン出力]
    Q --> R[ステートメントプラン出力]
    R --> S[PSCustomObject出力]
    C --> Q
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| パスエラー | パスがディレクトリでない | "Path ($Path) must be a directory" | ディレクトリパスを指定 |
| 接続エラー | SQL Server接続失敗 | "Failure" | 接続情報確認 |
| プラン取得エラー | DMV実行失敗 | "Issue collecting execution plans" | 権限確認 |
| ファイル書き込みエラー | XML保存失敗 | "Skipped query plan for $fileName because it is null." | nullプラン |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | プランキャッシュサイズに依存（数百〜数千） |
| 目標出力時間 | 数秒〜数分（プラン数に依存） |
| 同時出力数上限 | 1インスタンス/セッション |

## セキュリティ考慮事項

- 実行計画にはクエリ詳細（テーブル名、列名等）が含まれる
- VIEW SERVER STATE権限が必要
- 出力ファイルには機密性の高いスキーマ情報が含まれる可能性
- SQL Server 2005以上対応（MinimumVersion 9）

## 備考

- .sqlplanファイルはSSMSで直接開いてグラフィカルに表示可能
- バッチプランと単一ステートメントプランの両方を出力
- SqlHandleは前後の固定パターン部分をトリム
- Get-DbaExecutionPlanからのパイプライン入力に対応

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

DMVから取得するデータ構造と出力オブジェクトを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | PSCustomObject定義 |

**読解のコツ**: 行276-290のPSCustomObject構造に注目

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | パラメータと処理フロー |

**主要処理フロー**:
1. **行144-185**: beginブロック - Export-Plan内部関数定義
2. **行188-293**: processブロック - パス検証、クエリ実行、ファイル出力

#### Step 3: クエリ構築処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | 動的SQL構築 |

**主要処理フロー**:
- **行213-227**: SELECT句構築
- **行229-263**: WHERE条件動的構築

#### Step 4: ファイル出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | Export-Plan関数 |

**主要処理フロー**:
- **行146-154**: SqlHandle整形とファイル名生成
- **行156-167**: バッチプラン出力
- **行169-179**: 単一ステートメントプラン出力

### プログラム呼び出し階層図

```
Export-DbaExecutionPlan (PowerShell)
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（MinimumVersion 9）
    │
    ├─ ExecuteWithResults (SMO)
    │      └─ DMVクエリ実行
    │
    ├─ Export-Plan (内部関数)
    │      ├─ $queryPlan.Save() (BatchQueryPlanRaw)
    │      │      └─ -batch.sqlplanファイル出力
    │      │
    │      ├─ $statementPlan.Save() (SingleStatementPlanRaw)
    │      │      └─ .sqlplanファイル出力
    │      │
    │      └─ Select-DefaultView
    │             └─ PSCustomObject出力
    │
    └─ Write-Message
           └─ ログ出力
```

### データフロー図

```
[入力]                      [処理]                          [出力]

SqlInstance / InputObject  ┌──────────────────┐
         │                 │ Connect /        │
         └────────────────▶│ クエリ構築       │
                           └────────┬─────────┘
                                    │
                                    ▼
                           ┌──────────────────┐
                           │ DMVクエリ実行    │
                           │ dm_exec_*        │
                           └────────┬─────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
 ┌─────────────┐            ┌─────────────┐            ┌─────────────┐
 │ バッチプラン │            │ ステートメント │           │ メタデータ  │
 │ XML抽出     │            │ プランXML    │            │ 取得       │
 └──────┬──────┘            └──────┬──────┘            └──────┬──────┘
        │                           │                           │
        ▼                           ▼                           ▼
  -batch.sqlplan              .sqlplan                  PSCustomObject
    ファイル                   ファイル                   (パイプライン)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | ソース | メインコマンドレット |
| Get-DbaExecutionPlan.ps1 | `public/Get-DbaExecutionPlan.ps1` | ソース | パイプライン入力元 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1`（推定） | ソース | 出力プロパティ選択 |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
