# 画面設計書 167-診断クエリ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける診断クエリ実行機能（Invoke-DbaDiagnosticQuery）の画面設計書です。Glenn BerryのDMV診断クエリコレクションを実行し、SQL Serverのパフォーマンスと健全性を包括的に分析する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンス問題、構成の問題、健全性の課題を特定するために、Glenn Berryが開発・保守している包括的なDMVベース診断クエリを実行します。ブロッキング、高CPU使用率、メモリ圧迫、インデックスの断片化、構成上の問題など、一般的な問題の識別に役立ちます。

**画面へのアクセス方法**：PowerShellコマンドラインから `Invoke-DbaDiagnosticQuery` コマンドレットを実行してアクセスします。

**主要な操作・処理内容**：
1. SQL Serverバージョン（2005-2025、Azure SQL Database含む）を自動検出
2. バージョンに適した診断クエリスクリプトを選択
3. インスタンスレベルまたはデータベース固有のクエリを実行
4. 構造化されたPowerShellオブジェクトとして結果を返却

**画面遷移**：本機能は単独のコマンドレットとして動作します。出力をExport-DbaDiagnosticQueryにパイプして結果をエクスポート可能です。

**権限による表示制御**：診断クエリの多くはVIEW SERVER STATE権限が必要です。一部のクエリはsysadmin権限を必要とします。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 214 | Invoke-DbaDiagnosticQuery | 主機能 | 診断クエリの実行 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |
| 64 | Get-DbaDatabase | 内部呼出 | データベース一覧の取得 |
| 215 | Export-DbaDiagnosticQuery | 連携機能 | 診断結果のエクスポート |

## 画面種別

CLI（コマンドラインインターフェース）- 診断・分析

## URL/ルーティング

PowerShellコマンド: `Invoke-DbaDiagnosticQuery`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Database | object[] | No | 診断対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| Path | FileInfo | No | カスタム診断クエリスクリプトのディレクトリ |
| QueryName | string[] | No | 実行する診断クエリ名（指定時のみ実行） |
| ExcludeQuery | object[] | No | 除外する診断クエリ名 |
| UseSelectionHelper | switch | No | インタラクティブなクエリ選択グリッドを表示 |
| InstanceOnly | switch | No | インスタンスレベルクエリのみ実行 |
| DatabaseSpecific | switch | No | データベース固有クエリのみ実行 |
| ExcludeQueryTextColumn | switch | No | Complete Query Textカラムを除外 |
| ExcludePlanColumn | switch | No | Query Planカラムを除外 |
| NoColumnParsing | switch | No | カラム解析を無効化（高速化） |
| OutputPath | string | No | クエリエクスポート先ディレクトリ |
| ExportQueries | switch | No | クエリをSQLファイルとしてエクスポート |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Number | int | 診断クエリ番号 |
| Name | string | 診断クエリ名 |
| Description | string | クエリの説明 |
| DatabaseSpecific | bool | データベース固有クエリか否か |
| Database | string | 対象データベース名（DB固有クエリの場合） |
| Notes | string | 状態ノート（Empty Result/WhatIf等） |
| Result | DataRow[] | 診断クエリの結果データ |

## 表示項目

出力オブジェクトのすべてのプロパティがPowerShellコンソールに表示されます。Result プロパティには各診断クエリの詳細な結果が DataRow 形式で含まれます。

## イベント仕様

### 1-コマンド実行

1. **スクリプト解析**（行190-243）: beginブロックで診断クエリスクリプトを解析
2. **SQL Server接続**（行250-254）: Connect-DbaInstanceでサーバーに接続
3. **バージョン検出**（行257-284）: SQL Serverバージョンを検出し適切なスクリプト選択
4. **データベース取得**（行286-292）: Get-DbaDatabase で対象データベースを取得
5. **クエリ実行**（行339-498）: 各診断クエリを順次実行
6. **結果出力**（行364-395, 446-478）: PSCustomObjectとして結果を出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 診断クエリ実行 | 各種DMV/システムビュー | SELECT | 診断情報の収集 |
| クエリエクスポート | ファイルシステム | WRITE | SQLファイルの書き出し |

### 主要な参照DMV

- sys.dm_exec_requests
- sys.dm_exec_sessions
- sys.dm_exec_query_stats
- sys.dm_os_wait_stats
- sys.dm_db_index_physical_stats
- その他多数のシステムビュー

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 接続失敗時 | "Failure" - ConnectionError |
| Error | スクリプト未発見 | "Unable to download scripts, do you have an internet connection?" |
| Warning | スクリプト未発見 | "Diagnostic scripts not found in {Path}. Using the ones within the module." |
| Output | 選択なし | "No query selected through SelectionHelper, halting script execution" |
| Verbose | 処理中 | "Collecting diagnostic query data from server: {instance}" |
| Verbose | 処理完了 | "Processed {QueryName} on {instance}" |
| Verbose | エラー時 | "Some error has occurred on Server: {instance} - Script: {QueryName}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| 診断クエリ実行失敗 | Write-Messageでエラーを記録し、次のクエリの処理を継続 |
| スクリプト解析失敗 | Stop-Functionで終了 |
| UseSelectionHelper選択なし | Write-Messageで通知して終了 |

## 備考

- Glenn Berryが開発・保守する診断クエリコレクションを使用
- SQL Server 2005から2025、Azure SQL Databaseに対応
- バージョン固有のクエリを自動選択
- -UseSelectionHelperでOut-GridViewによるインタラクティブ選択が可能
- -ExportQueriesでSQLファイルとしてエクスポート可能
- 参考: https://glennsqlperformance.com/resources/

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造と診断クエリスクリプトの形式を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行97-119の.OUTPUTSセクションで出力プロパティを確認 |

**読解のコツ**: 各診断クエリが個別のPSCustomObjectとして出力され、Resultプロパティに実際のクエリ結果が含まれる点に注目。

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

パラメータ定義とスクリプト解析処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行168-189のパラメータ定義 |
| 2-2 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行190-244のbeginブロック（スクリプト解析） |

**主要処理フロー**:
1. **行206-208**: デフォルトのスクリプトパス設定（bin\diagnosticquery）
2. **行210-243**: スクリプトファイルの解析とバージョン別管理

#### Step 3: バージョン検出とクエリ選択を理解する

SQL Serverバージョン検出と適切なスクリプト選択を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行257-284のバージョン検出ロジック |
| 3-2 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行294のスクリプト選択 |

**主要処理フロー**:
- **行257-271**: VersionMajor/VersionMinorからSQL Serverバージョン文字列を決定
- **行274-280**: SQL Server 2016のSP別処理
- **行282-284**: Azure SQL Databaseの検出

#### Step 4: クエリ実行処理を理解する

診断クエリの実行と結果出力を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行339-414のインスタンスレベルクエリ処理 |
| 4-2 | Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | 行415-497のデータベース固有クエリ処理 |

**主要処理フロー**:
- **行344-351**: ExportQueriesモードでのファイル出力
- **行361**: $server.Query()でクエリ実行
- **行364-395**: 結果をPSCustomObjectとして出力
- **行440-444**: Azure SQL DB対応（1パラメータQuery呼び出し）

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

```
Invoke-DbaDiagnosticQuery
    |
    +-- [beginブロック] スクリプト解析 (行190-244)
    |       |
    |       +-- Get-ChildItem (行211)
    |       |       └── 診断クエリスクリプト取得
    |       |
    |       └── Invoke-DbaDiagnosticQueryScriptParser (行235)
    |               └── スクリプト解析
    |
    +-- Connect-DbaInstance (行251)
    |       └── SQL Serverへの接続
    |
    +-- バージョン検出 (行257-284)
    |       └── SQL Serverバージョン文字列決定
    |
    +-- Get-DbaDatabase (行288-291)
    |       └── 対象データベース取得
    |
    +-- [UseSelectionHelper]
    |       └── Invoke-DiagnosticQuerySelectionHelper (行298)
    |               └── Out-GridView選択UI
    |
    +-- [各クエリのループ]
    |       |
    |       +-- [ExportQueries]
    |       |       └── Out-File (行349, 423)
    |       |               └── SQLファイル出力
    |       |
    |       +-- $server.Query() (行361, 441-443)
    |       |       └── クエリ実行
    |       |
    |       └── PSCustomObject出力 (行364-395, 446-478)
    |               └── 結果オブジェクト生成
    |
    └── Write-Progress (行502)
            └── 進捗完了通知
```

### データフロー図

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

SqlInstance ─────────────────┐
                             │
SqlCredential ───────────────┼──> Connect-DbaInstance
                             │          │
Path ────────────────────────┼──> スクリプトパス決定
                             │          │
                             │          v
                             │   スクリプト解析
                             │   (Invoke-DbaDiagnosticQueryScriptParser)
                             │          │
                             │          v
                             │   バージョン検出
                             │   (VersionMajor/Minor)
                             │          │
                             │          v
                             │   [バージョン別スクリプト選択]
                             │          │
Database ────────────────────┼──> Get-DbaDatabase
ExcludeDatabase ─────────────┘          │
                                        v
QueryName ───────────────────┐   [クエリフィルタリング]
ExcludeQuery ────────────────┘          │
                                        v
UseSelectionHelper ──────────────> Out-GridView (選択UI)
                                        │
                                        v
InstanceOnly ────────────────┐   [クエリ実行ループ]
DatabaseSpecific ────────────┘          │
                                        v
                             ┌─> [ExportQueries]
                             │        │
                             │        v
OutputPath ──────────────────┴──> Out-File ───────> SQLファイル
                                        │
                                        v
                                $server.Query()
                                        │
                                        v
                                PSCustomObject
                                (診断結果オブジェクト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDiagnosticQuery.ps1 | `public/Invoke-DbaDiagnosticQuery.ps1` | ソース | 診断クエリ実行の実装 |
| Export-DbaDiagnosticQuery.ps1 | `public/Export-DbaDiagnosticQuery.ps1` | ソース | 診断結果のエクスポート |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース一覧取得 |
| Invoke-DbaDiagnosticQueryScriptParser.ps1 | `internal/Invoke-DbaDiagnosticQueryScriptParser.ps1` | 内部関数 | スクリプト解析 |
| SQLServerDiagnosticQueries_*.sql | `bin/diagnosticquery/` | スクリプト | Glenn Berry診断クエリ |
