# 帳票設計書 2-Export-DbaDiagnosticQuery

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbaDiagnosticQueryコマンドレットに関する帳票設計書です。Glenn Berryの診断クエリ結果をCSVまたはExcelファイルに変換し、実行計画を.sqlplanファイルとして抽出する機能について記載しています。

### 本帳票の処理概要

Export-DbaDiagnosticQueryは、Invoke-DbaDiagnosticQueryから返されるPowerShellオブジェクトを処理し、CSVファイルまたはExcelワークシートとして保存するコマンドレットです。診断クエリ結果の分析、レポーティング、およびベンダーとの情報共有に使用されます。

**業務上の目的・背景**：SQL Serverのパフォーマンス分析やトラブルシューティングにおいて、Glenn Berryが作成した業界標準の診断クエリを実行し、その結果をファイルベースで保存・共有する必要があります。コンプライアンス文書化、パフォーマンス分析、PowerShellオブジェクトよりも従来のファイル形式を好むチームとの連携において特に有用です。

**帳票の利用シーン**：
1. SQL Serverのパフォーマンス診断レポート作成
2. ベンダーサポートへの診断情報提供
3. 定期的なパフォーマンストレンド分析のためのデータ蓄積
4. コンプライアンス監査用のサーバー状態ドキュメント化

**主要な出力内容**：
1. CSVファイル（診断クエリごとに個別ファイル）
2. Excelワークブック（診断クエリをワークシートとして統合）
3. .sqlplanファイル（実行計画のXMLエクスポート）
4. .sqlファイル（クエリテキストのエクスポート）

**帳票の出力タイミング**：Invoke-DbaDiagnosticQueryの結果をパイプラインで受け取り、Export-DbaDiagnosticQueryを実行した時点で即座にファイルが生成されます。

**帳票の利用者**：データベース管理者（DBA）、パフォーマンスエンジニア、システム管理者、サポートエンジニア

## 帳票種別

診断レポート（CSV / Excel / 実行計画ファイル）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbaDiagnosticQueryコマンド実行 |
| N/A | PowerShell ISE | N/A | スクリプト実行 |
| N/A | VS Code Terminal | N/A | スクリプト実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | CSV / Excel (.xlsx) / SQLPlan (.sqlplan) / SQL (.sql) |
| 用紙サイズ | N/A（データファイル） |
| 向き | N/A |
| ファイル名 | 自動生成（インスタンス名-DQ-タイムスタンプ.形式） |
| 出力方法 | ディレクトリへのファイル書き込み |
| 文字コード | デフォルトエンコーディング |

### ファイル命名規則

| ファイル種別 | 命名パターン | 例 |
|------------|-------------|---|
| Excel（インスタンス単位） | {SqlInstance}-DQ-{Suffix}.xlsx | SQL01-DQ-20231215120530ms.xlsx |
| Excel（DB単位） | {SqlInstance}-DQ-{Database}-{Suffix}.xlsx | SQL01-DQ-AdventureWorks-20231215120530ms.xlsx |
| CSV（インスタンス単位） | {SqlInstance}-DQ-{Number}-{QueryName}-{Suffix}.csv | SQL01-DQ-1-CPUInfo-20231215120530ms.csv |
| CSV（DB単位） | {SqlInstance}-{Database}-DQ-{Number}-{QueryName}-{Suffix}.csv | SQL01-AdventureWorks-DQ-5-IndexUsage-20231215120530ms.csv |
| 実行計画 | {SqlInstance}-DQ-{Number}-{QueryName}-{PlanNo}-{Suffix}.sqlplan | SQL01-DQ-10-TopQueries-1-20231215120530ms.sqlplan |
| SQLテキスト | {SqlInstance}-DQ-{Number}-{QueryName}-{SqlNo}-{Suffix}.sql | SQL01-DQ-10-TopQueries-1-20231215120530ms.sql |

### Excel固有設定

| 項目 | 内容 |
|-----|------|
| シート名 | 診断クエリ名（Name） |
| 自動サイズ調整 | 有効（AutoSize） |
| 自動フィルター | 有効（AutoFilter） |
| ヘッダー太字 | 有効（BoldTopRow） |
| ヘッダー固定 | 有効（FreezeTopRow） |

## 帳票レイアウト

### レイアウト概要

各診断クエリの結果が個別のファイルまたはワークシートとして出力されます。

```
┌─────────────────────────────────────┐
│        診断クエリ結果ファイル          │
├─────────────────────────────────────┤
│         ヘッダー行（列名）            │
├─────────────────────────────────────┤
│           データ行1                 │
│           データ行2                 │
│             ...                    │
│           データ行N                 │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│      実行計画ファイル (.sqlplan)      │
├─────────────────────────────────────┤
│         XML実行計画データ            │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 診断クエリ列名 | 各診断クエリで定義された列名 | Invoke-DbaDiagnosticQuery結果 | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | 診断データ | 診断クエリの実行結果データ | Invoke-DbaDiagnosticQuery | データ型に応じた形式 | 自動調整 |

### フッター部

ファイルにはフッター部はありません。コマンドは出力ファイルのFileInfo オブジェクトを返します。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Name | ファイル名 | System.IO.FileInfo | 文字列 |
| 2 | FullName | 完全パス | System.IO.FileInfo | 文字列 |
| 3 | Directory | ディレクトリ | System.IO.FileInfo | オブジェクト |
| 4 | Length | ファイルサイズ（バイト） | System.IO.FileInfo | 整数 |
| 5 | CreationTime | 作成日時 | System.IO.FileInfo | DateTime |
| 6 | LastWriteTime | 最終更新日時 | System.IO.FileInfo | DateTime |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| InputObject | Invoke-DbaDiagnosticQueryからの診断結果 | Yes |
| ConvertTo | 出力形式（Excel / Csv） | No（デフォルト: Csv） |
| Path | 出力ディレクトリ | No（デフォルト: DbatoolsExportパス） |
| Suffix | ファイル名サフィックス | No（デフォルト: タイムスタンプ） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 入力オブジェクトの順序に依存 | N/A |

### 改ページ条件

ファイルベースのため改ページは適用されません。Excelの場合は診断クエリごとに別シートに出力されます。

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

### 参照テーブル一覧

本コマンドは直接データベースを参照しません。Invoke-DbaDiagnosticQueryの結果オブジェクトを入力として処理します。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | パイプライン入力 | N/A |

### 入力オブジェクト構造

| プロパティ | 説明 | 用途 |
|-----------|------|------|
| Result | 診断クエリの結果データ | CSV/Excelデータソース |
| Name | 診断クエリ名 | ファイル名/シート名 |
| SqlInstance | インスタンス名 | ファイル名プレフィックス |
| Database | データベース名 | DB固有ファイル名用 |
| Number | クエリ番号 | ファイル名識別子 |
| DatabaseSpecific | DB固有クエリフラグ | 出力ファイル名決定 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| ファイル名 | インスタンス名+クエリ番号+クエリ名+サフィックス | N/A | 特殊文字は除去 |
| クエリ名サニタイズ | Remove-InvalidFileNameChars | N/A | ファイル名不正文字除去 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaDiagnosticQuery実行] --> B{ConvertTo判定}
    B -->|Excel| C[ImportExcelモジュール読み込み]
    B -->|CSV| D[パス確認/作成]
    C --> D
    D --> E[パイプライン入力処理]
    E --> F{実行計画列存在?}
    F -->|Yes| G[.sqlplanファイル出力]
    F -->|No| H{クエリテキスト列存在?}
    G --> H
    H -->|Yes| I[.sqlファイル出力]
    H -->|No| J{ConvertTo判定}
    I --> J
    J -->|Excel| K[Export-Excelでシート出力]
    J -->|CSV| L[Export-CsvでCSV出力]
    K --> M[FileInfo出力]
    L --> M
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| モジュール不足 | Excel出力時にImportExcelモジュール未インストール | "Failed to load module, exporting to Excel feature is not available..." | ImportExcelモジュールをインストール |
| パスエラー | パスがディレクトリでない | "Path ($Path) must be a directory" | ディレクトリパスを指定 |
| 空結果 | 診断クエリ結果がnull | "Result was empty for $name" | 入力データを確認 |
| サポート外入力 | 非対応の入力データ型 | "Unsupported input data..." | Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの結果を使用 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 診断クエリ数に依存（通常数十〜100以上） |
| 目標出力時間 | 数秒〜数分（データ量とファイル数に依存） |
| 同時出力数上限 | 1セッション複数ファイル |

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

- 診断クエリ結果にはサーバー構成情報が含まれる可能性があり、出力ファイルのアクセス管理が必要
- 実行計画ファイルにはクエリ詳細が含まれるため、機密情報として扱う
- 出力ディレクトリの権限設定を適切に行うこと

## 備考

- ImportExcelモジュール（https://github.com/dfinke/ImportExcel）が必要（Excel出力時）
- サフィックスのデフォルトはyyyyMMddHHmmssms形式のタイムスタンプ
- 実行計画列名は複数パターン対応（Query Plan, QueryPlan, Query_Plan, query_plan_xml）
- クエリテキスト列名も複数パターン対応（Complete Query Text, QueryText, Query Text, Query_Text, query_sql_text）

---

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

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

### 推奨読解順序

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

入力オブジェクトはInvoke-DbaDiagnosticQueryからの結果オブジェクトです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 入力オブジェクトの構造を理解 |

**読解のコツ**: Result, Name, SqlInstance, Database, Number, DatabaseSpecificプロパティに注目

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

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

**主要処理フロー**:
1. **行102-123**: beginブロック - ImportExcel読み込み、パス確認
2. **行124-214**: processブロック - 各診断結果の処理
3. **行127-132**: 入力データの展開（Result, Name, SqlInstance等）

#### Step 3: 実行計画/クエリテキスト抽出処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaDiagnosticQuery.ps1 | `public/Export-DbaDiagnosticQuery.ps1` | 列名検出と特殊ファイル出力 |

**主要処理フロー**:
- **行144-163**: 実行計画列の検出と.sqlplan出力
- **行165-187**: クエリテキスト列の検出と.sql出力

#### Step 4: CSV/Excel出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaDiagnosticQuery.ps1 | `public/Export-DbaDiagnosticQuery.ps1` | 形式別出力処理 |

**主要処理フロー**:
- **行189-199**: Excel出力（Export-Excel使用）
- **行201-211**: CSV出力（Export-Csv使用）

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

```
Export-DbaDiagnosticQuery (PowerShell)
    │
    ├─ Import-Module ImportExcel (外部モジュール)
    │      └─ Excel機能の読み込み
    │
    ├─ Test-Path / New-Item (PowerShell)
    │      └─ パス確認/作成
    │
    ├─ Remove-InvalidFileNameChars (dbatools内部関数)
    │      └─ ファイル名サニタイズ
    │
    ├─ Join-DbaPath (dbatools内部関数)
    │      └─ パス結合
    │
    ├─ Out-File (PowerShell)
    │      └─ .sqlplan/.sql出力
    │
    ├─ Export-Excel (ImportExcelモジュール)
    │      └─ Excelワークブック出力
    │
    └─ Export-Csv (PowerShell)
           └─ CSVファイル出力
```

### データフロー図

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

Invoke-DbaDiagnosticQuery    ┌──────────────────┐
     └─ Result ─────────────▶│  列名検出処理    │
                             │ (Query Plan等)   │
                             └────────┬─────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    │                 │                 │
                    ▼                 ▼                 ▼
             ┌──────────┐     ┌──────────┐     ┌──────────┐
             │ 実行計画 │     │ クエリ   │     │ データ  │
             │  抽出    │     │ テキスト │     │  本体   │
             └────┬─────┘     └────┬─────┘     └────┬─────┘
                  │                 │                 │
                  ▼                 ▼                 ▼
             .sqlplan          .sqlファイル     CSV/Excel
              ファイル                            ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaDiagnosticQuery.ps1 | `public/Export-DbaDiagnosticQuery.ps1` | ソース | メインコマンドレット実装 |
| Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | ソース | 入力データ生成元 |
| Remove-InvalidFileNameChars.ps1 | `private/functions/Remove-InvalidFileNameChars.ps1`（推定） | ソース | ファイル名サニタイズ |
| Join-DbaPath.ps1 | `private/functions/Join-DbaPath.ps1`（推定） | ソース | パス結合ユーティリティ |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
