# 機能設計書 293-Export-DbaExecutionPlan

## 概要

本ドキュメントは、SQL Serverのプランキャッシュから実行プランを抽出し、.sqlplanファイルとして保存するExport-DbaExecutionPlan機能について記述する。

### 本機能の処理概要

Export-DbaExecutionPlanは、SQL Serverの動的管理ビュー（DMV）を使用してプランキャッシュから実行プランを取得し、XML形式の.sqlplanファイルとしてエクスポートするコマンドレットである。生成されたファイルはSQL Server Management Studioで直接開いて詳細な分析が可能。

**業務上の目的・背景**：クエリパフォーマンスの問題を調査する際、実行プランの分析は不可欠である。しかし、本番環境でリアルタイムにプランをキャプチャすることは負荷やタイミングの問題がある。本機能はプランキャッシュに蓄積された実行プランを一括でエクスポートし、オフラインでの詳細分析を可能にする。DMVを手動でクエリする必要がなくなり、パフォーマンストラブルシューティングの効率が大幅に向上する。

**機能の利用シーン**：
- パフォーマンス問題発生時の実行プラン一括収集
- 定期的なパフォーマンス監査のためのプラン保存
- デプロイ前後の実行プラン比較分析
- DBA間でのプラン共有（.sqlplanファイルによる）
- 問題クエリの特定と最適化検討

**主要な処理内容**：
1. sys.dm_exec_query_stats DMVからクエリ統計を取得
2. sys.dm_exec_text_query_plan、sys.dm_exec_query_plan、sys.dm_exec_sql_textをCROSS APPLYで結合
3. データベース、作成日時、最終実行日時によるフィルタリング
4. 単一ステートメントプランとバッチクエリプランのXML取得
5. .sqlplanファイルとしてディスクに保存

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 215 | 実行プラン | 補助機能 | 実行プランのエクスポート |

## 機能種別

データ出力 / ファイル生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes（NotPiped） | 対象SQL Serverインスタンス | SQL Server 2005以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Database | object[] | No | フィルタ対象データベース | - |
| ExcludeDatabase | object[] | No | 除外データベース | - |
| Path | string | No | 出力ディレクトリ。デフォルト: DbatoolsExport設定値 | ディレクトリ存在確認 |
| SinceCreation | datetime | No | プラン作成日時フィルタ（以降） | - |
| SinceLastExecution | datetime | No | 最終実行日時フィルタ（以降） | - |
| InputObject | object[] | Yes（Piped） | パイプライン入力（Get-DbaExecutionPlanから） | - |
| EnableException | switch | No | 例外を有効にする | - |
| WhatIf | switch | No | 実行内容のプレビュー | - |
| Confirm | 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 | データベース名 |
| SqlHandle | string | SQLハンドル（16進数） |
| CreationTime | datetime | プラン作成日時 |
| LastExecutionTime | datetime | 最終実行日時 |
| OutputFile | string | 出力ファイルパス |

### 出力先

- ファイルシステム（.sqlplanファイル）
- パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Pathがディレクトリか確認
2. InputObjectがある場合
   └─ Export-Plan関数で直接エクスポート
3. SqlInstanceが指定された場合
   └─ Connect-DbaInstanceで接続（MinimumVersion=9）
   └─ DMVクエリの構築（フィルタ条件付加）
   └─ クエリ実行
   └─ 各行に対してExport-Plan関数を呼び出し
4. Export-Plan関数
   └─ ファイル名の生成（instance-db-position-sqlhandle形式）
   └─ バッチクエリプランの保存（-batch.sqlplan）
   └─ 単一ステートメントプランの保存（.sqlplan）
   └─ 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject?}
    B -->|Yes| C[Export-Plan呼び出し]
    B -->|No| D[インスタンス接続]
    D --> E[DMVクエリ構築]
    E --> F{フィルタ条件追加}
    F --> G[クエリ実行]
    G --> H{各行ループ}
    H --> I[PSCustomObject作成]
    I --> J[Export-Plan呼び出し]
    C --> K[ファイル名生成]
    J --> K
    K --> L[バッチプラン保存]
    L --> M[ステートメントプラン保存]
    M --> N[結果出力]
    N --> H
    H -->|完了| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイル命名規則 | instance-database-position-sqlhandle形式 | 常時 |
| BR-002 | バッチプラン接尾辞 | バッチクエリプランは-batch.sqlplan | 常時 |
| BR-003 | SQLハンドル短縮 | 先頭と末尾のゼロパディングを除去 | 常時 |
| BR-004 | バージョン要件 | SQL Server 2005以上が必須 | 接続時 |

### 計算ロジック

SQLハンドルの変換: バイト配列から16進数文字列へ変換し、先頭の"0x02000000"と末尾のゼロを除去

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プラン取得 | 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 | Database/ExcludeDatabase/SinceCreation/SinceLastExecutionでフィルタ | CROSS APPLYで他DMVと結合 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| PathError | パスエラー | Pathがディレクトリでない | ディレクトリパスの指定 |
| FileWriteError | ファイル書き込みエラー | プランがnullまたは書き込み失敗 | ディスク容量・権限の確認 |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- 大量のプランをエクスポートする場合はディスク容量を確認すること
- SinceCreationやSinceLastExecutionを使用して出力量を制限することを推奨
- Get-DbaExecutionPlanと組み合わせて使用可能

---

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

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

### 推奨読解順序

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

DMVから取得するデータとPSCustomObjectの構造を理解する。

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

**読解のコツ**: SqlHandleとPlanHandleはバイト配列から16進数文字列に変換される。

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

begin/processブロックの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | beginブロック内のExport-Plan関数（146-185行目） |

**主要処理フロー**:
1. **150-155行目**: ファイル名の生成（インスタンス-DB-位置-ハンドル形式）
2. **157-167行目**: バッチクエリプランの保存
3. **169-179行目**: 単一ステートメントプランの保存
4. **181-184行目**: 出力オブジェクトの作成

#### Step 3: DMVクエリを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaExecutionPlan.ps1 | `public/Export-DbaExecutionPlan.ps1` | processブロック（188-293行目） |

**主要処理フロー**:
- **213-227行目**: SELECT文とFROM句の構築（CROSS APPLY使用）
- **229-261行目**: WHERE句の動的構築（フィルタ条件）
- **266-270行目**: クエリ実行とデータ取得

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

```
Export-DbaExecutionPlan
    │
    ├─ begin
    │      └─ Export-Plan (内部関数定義)
    │             ├─ ファイル名生成
    │             ├─ BatchQueryPlanRaw.Save()
    │             ├─ SingleStatementPlanRaw.Save()
    │             └─ Select-DefaultView
    │
    └─ process
           │
           ├─ [InputObject指定時]
           │      └─ Export-Plan呼び出し
           │
           └─ [SqlInstance指定時]
                  │
                  ├─ Connect-DbaInstance
                  │
                  ├─ DMVクエリ構築
                  │      ├─ SELECT句
                  │      ├─ FROM句 (CROSS APPLY)
                  │      └─ WHERE句 (動的)
                  │
                  ├─ ExecuteWithResults
                  │
                  └─ foreach row
                         └─ Export-Plan呼び出し
```

### データフロー図

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

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

                                        │
                                        ▼
                               PSCustomObject作成
                                        │
                                        ▼
                               Export-Plan関数
                                        │
                        ┌───────────────┼───────────────┐
                        ▼               ▼               ▼
                 -batch.sqlplan    .sqlplan       Pipeline出力
```

### 関連ファイル一覧

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