# 機能設計書 296-Get-DbaExecutionPlan

## 概要

本ドキュメントは、SQL Serverのプランキャッシュからキャッシュされた実行プランとメタデータを取得するGet-DbaExecutionPlan機能について記述する。

### 本機能の処理概要

Get-DbaExecutionPlanは、SQL Serverの動的管理ビュー（DMV）を使用してプランキャッシュから実行プランを取得するコマンドレットである。取得したプランはパフォーマンス分析やトラブルシューティングに使用でき、Export-DbaExecutionPlanにパイプで渡して.sqlplanファイルとして保存できる。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を調査する際、実行プランの分析は不可欠である。sys.dm_exec_query_stats等のDMVを直接クエリするには専門知識が必要であり、結果の解釈も複雑である。本機能はDMVへのアクセスを簡素化し、実行プランの詳細なメタデータ（コスト、推定行数、最適化レベル等）を構造化された形で提供する。これにより、リソース集約型のクエリの特定やプラン変更の分析が容易になる。

**機能の利用シーン**：
- パフォーマンス問題のトラブルシューティング
- リソース集約型クエリの特定
- デプロイ後の実行プラン変更の検出
- 定期的なパフォーマンス監査
- クエリ最適化の検討材料収集

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（MinimumVersion=9: SQL Server 2005以上）
2. sys.dm_exec_query_stats、sys.dm_exec_text_query_plan、sys.dm_exec_query_plan、sys.dm_exec_sql_textのCROSS APPLYクエリ実行
3. フィルタ条件（Database、ExcludeDatabase、SinceCreation、SinceLastExecution、ExcludeEmptyQueryPlan）の適用
4. 実行プランXMLの解析とメタデータ抽出
5. 構造化されたPSCustomObjectの出力

**関連システム・外部連携**：Export-DbaExecutionPlanへのパイプライン出力をサポート。SQLServer Management Studioで.sqlplanファイルを開いて詳細分析可能。

**権限による制御**：VIEW SERVER STATE権限が必要（DMVへのアクセス）。SQL Server 2005（バージョン9）以上が必須。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 215 | 実行プラン | 主機能 | 実行プランの取得 |

## 機能種別

データ取得 / パフォーマンス分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2005以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Database | object[] | No | フィルタ対象データベース | - |
| ExcludeDatabase | object[] | No | 除外データベース | - |
| SinceCreation | datetime | No | プラン作成日時フィルタ（以降） | - |
| SinceLastExecution | datetime | No | 最終実行日時フィルタ（以降） | - |
| ExcludeEmptyQueryPlan | switch | No | 空のクエリプランを除外 | - |
| Force | switch | No | 全カラムを返す（生DMV出力） | - |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- sys.dm_exec_query_stats（クエリ実行統計）
- sys.dm_exec_text_query_plan（単一ステートメントプラン）
- sys.dm_exec_query_plan（バッチクエリプラン）
- sys.dm_exec_sql_text（SQLテキスト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| DatabaseName | string | データベース名 |
| ObjectName | string | オブジェクト名（NULL可） |
| QueryPosition | int | バッチ内のステートメント位置 |
| SqlHandle | string | SQLハンドル（16進数） |
| PlanHandle | string | プランハンドル（16進数） |
| CreationTime | datetime | プラン作成日時 |
| LastExecutionTime | datetime | 最終実行日時 |
| StatementCondition | xml | ステートメント条件XML |
| StatementSimple | xml | 単純ステートメントXML |
| StatementId | int | ステートメントID |
| StatementCompId | int | ステートメントコンパイルID |
| StatementType | string | ステートメントタイプ |
| RetrievedFromCache | bool | キャッシュから取得 |
| StatementSubTreeCost | decimal | サブツリーコスト |
| StatementEstRows | decimal | 推定行数 |
| SecurityPolicyApplied | bool | セキュリティポリシー適用 |
| StatementOptmLevel | int | 最適化レベル |
| QueryHash | string | クエリハッシュ |
| QueryPlanHash | string | クエリプランハッシュ |
| StatementOptmEarlyAbortReason | string | 早期中断理由 |
| CardinalityEstimationModelVersion | int | カーディナリティ推定バージョン |
| ParameterizedText | string | パラメータ化テキスト |
| StatementSetOptions | string | SETオプション |
| QueryPlan | xml | クエリプランXML |
| BatchConditionXml | xml | バッチ条件XML |
| BatchSimpleXml | xml | バッチ単純XML |

### 出力先

パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
2. インスタンス接続（MinimumVersion=9）
3. DMVクエリの構築
   └─ Force指定時: SELECT *
   └─ 通常時: 特定カラムを選択
   └─ WHERE句の動的構築（フィルタ条件）
4. クエリ実行
5. 結果の処理
   └─ Force指定時: 生データを返す
   └─ 通常時: XMLを解析してPSCustomObjectを構築
6. パイプラインへの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各インスタンスループ}
    B --> C[Connect-DbaInstance]
    C --> D{Force指定?}
    D -->|Yes| E[SELECT * クエリ構築]
    D -->|No| F[特定カラムクエリ構築]
    E --> G[WHERE句追加]
    F --> G
    G --> H[クエリ実行]
    H --> I{Force指定?}
    I -->|Yes| J[生データ出力]
    I -->|No| K[XML解析]
    K --> L[PSCustomObject構築]
    L --> M[Select-DefaultView]
    M --> B
    J --> B
    B -->|完了| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2005以上が必須 | 接続時 |
| BR-002 | Force出力 | 全DMVカラムを生データで返す | Force指定時 |
| BR-003 | ハンドル変換 | バイト配列を16進数文字列に変換 | 常時（通常モード） |
| BR-004 | XML解析 | ShowPlanXMLからステートメント情報を抽出 | 常時（通常モード） |

### 計算ロジック

- SqlHandle/PlanHandle変換: バイト配列から16進数文字列へ（0xプレフィックス付き）
- QueryPosition: ROW_NUMBER() OVER (ORDER BY Statement_Start_offset)で算出

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 統計取得 | sys.dm_exec_query_stats | SELECT | クエリ統計 |
| テキストプラン取得 | sys.dm_exec_text_query_plan | SELECT | 単一ステートメントプラン |
| クエリプラン取得 | sys.dm_exec_query_plan | SELECT | バッチクエリプラン |
| SQLテキスト取得 | sys.dm_exec_sql_text | SELECT | SQLテキスト |

### テーブル別操作詳細

#### sys.dm_exec_query_stats

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | sql_handle, plan_handle, creation_time, last_execution_time, statement_start_offset, statement_end_offset | フィルタ条件による | CROSS APPLYで他DMVと結合 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| QueryFailure | クエリエラー | DMVクエリ実行失敗 | 権限の確認 |

### リトライ仕様

リトライ処理なし。エラー発生時は次のインスタンスの処理へ継続。

## トランザクション仕様

読み取り専用操作。トランザクション制御なし。

## パフォーマンス要件

大規模なプランキャッシュを持つサーバーでは処理時間が長くなる可能性あり。フィルタパラメータの使用を推奨。

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

- VIEW SERVER STATE権限が必要
- 実行プランにはクエリテキストやパラメータ値が含まれる可能性がある
- 機密情報を含む可能性のあるデータの取り扱いに注意

## 備考

- Export-DbaExecutionPlanにパイプで渡すことで.sqlplanファイルとして保存可能
- Forceオプションを使用すると全DMVカラムが取得できるが、XMLの解析は行われない
- SinceCreation/SinceLastExecutionフィルタで出力量を制限することを推奨

---

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

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

### 推奨読解順序

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

PSCustomObjectの出力構造とXML解析ポイントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaExecutionPlan.ps1 | `public/Get-DbaExecutionPlan.ps1` | 出力オブジェクト構造（236-270行目） |

**読解のコツ**: ShowPlanXMLの構造（BatchSequence.Batch.Statements.StmtSimple）を理解することが重要。

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

processブロックでのDMVクエリ構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaExecutionPlan.ps1 | `public/Get-DbaExecutionPlan.ps1` | processブロック（159-277行目） |

**主要処理フロー**:
1. **164行目**: Connect-DbaInstanceでMinimumVersion 9を指定
2. **169-180行目**: Force指定によるSELECT句の分岐
3. **182-187行目**: FROM句（CROSS APPLY使用）
4. **189-222行目**: WHERE句の動的構築
5. **227-271行目**: 結果の処理とXML解析

#### Step 3: XML解析を理解する

実行プランXMLからのメタデータ抽出を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaExecutionPlan.ps1 | `public/Get-DbaExecutionPlan.ps1` | XML解析部分（231-269行目） |

**主要処理フロー**:
- **231行目**: SingleStatementPlanからShowPlanXMLをパース
- **234行目**: QueryPlan.Warningsからプラン警告を抽出
- **247-265行目**: StmtSimpleの各プロパティを出力オブジェクトにマッピング

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

```
Get-DbaExecutionPlan
    │
    └─ process
           │
           ├─ foreach $instance
           │      │
           │      ├─ Connect-DbaInstance
           │      │      └─ MinimumVersion 9
           │      │
           │      ├─ [Force指定時]
           │      │      └─ SELECT * クエリ
           │      │
           │      ├─ [通常時]
           │      │      └─ 特定カラムクエリ
           │      │
           │      ├─ WHERE句構築
           │      │      ├─ Database フィルタ
           │      │      ├─ SinceCreation フィルタ
           │      │      ├─ SinceLastExecution フィルタ
           │      │      ├─ ExcludeDatabase フィルタ
           │      │      └─ ExcludeEmptyQueryPlan フィルタ
           │      │
           │      └─ Server.Query($sql)
           │             │
           │             └─ [通常時] XML解析
           │                    ├─ [xml]$row.SingleStatementPlan
           │                    └─ PSCustomObject構築
           │
           └─ Select-DefaultView
```

### データフロー図

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

sys.dm_exec_query_stats ─────▶ SELECT + CROSS APPLY
sys.dm_exec_text_query_plan ─▶                    ─────▶ DataRows
sys.dm_exec_query_plan ──────▶
sys.dm_exec_sql_text ────────▶

                                        │
                      ┌─────────────────┴─────────────────┐
                      ▼                                   ▼
                 [Force]                             [通常]
                      │                                   │
                      ▼                                   ▼
                 生データ出力                      XML解析
                                                         │
                                                         ▼
                                                  PSCustomObject
                                                         │
                                                         ▼
                                                 Select-DefaultView
                                                         │
                                                         ▼
                                                    Pipeline
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaExecutionPlan.ps1 | `public/Get-DbaExecutionPlan.ps1` | ソース | メイン処理 |
| Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | ソース | パイプライン出力先 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
