# 機能設計書 297-Get-DbaQueryExecutionTime

## 概要

本ドキュメントは、SQL Serverインスタンスから最も高いCPU実行時間を持つストアドプロシージャとSQLステートメントを取得するGet-DbaQueryExecutionTime機能について記述する。

### 本機能の処理概要

Get-DbaQueryExecutionTimeは、SQL Serverの動的管理ビュー（DMV）からCPUワーカータイムデータを分析し、パフォーマンスボトルネックを特定するコマンドレットである。ストアドプロシージャ（sys.dm_exec_procedure_stats）とアドホッククエリ（sys.dm_exec_query_stats）の両方を対象に、実行時間ベースでソートされた結果を返す。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を調査する際、どのクエリが最もCPUリソースを消費しているかを特定することは重要である。手動でDMVをクエリして分析するには専門知識が必要であり、結果の統合も煩雑である。本機能はストアドプロシージャとアドホッククエリの両方を統合的に分析し、平均実行時間、最大実行時間、総ワーカータイム等の指標を提供する。これにより、パフォーマンスチューニングの優先順位付けが容易になる。

**機能の利用シーン**：
- パフォーマンス問題のトラブルシューティング
- ピーク時間帯のリソース集約型クエリの特定
- 定期的なパフォーマンス監査
- クエリ最適化の優先順位付け
- 本番環境の健全性チェック

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（MinimumVersion=10: SQL Server 2008以上）
2. CTEを使用したストアドプロシージャ統計とアドホッククエリ統計の統合クエリ実行
3. フィルタ条件（Database、ExcludeDatabase、MinExecs、MinExecMs、ExcludeSystem）の適用
4. 平均実行時間（AvgExec_ms）でソートされた結果の取得
5. 構造化されたPSCustomObjectの出力

**関連システム・外部連携**：なし

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 159 | クエリ実行時間 | 主機能 | クエリ実行時間の取得 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2008以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Database | object[] | No | フィルタ対象データベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | 除外データベース | ワイルドカード対応 |
| MaxResultsPerDb | int | No | データベースごとの最大結果数。デフォルト: 100 | - |
| MinExecs | int | No | 最小実行回数フィルタ。デフォルト: 100 | - |
| MinExecMs | int | No | 最小平均実行時間（ミリ秒）フィルタ。デフォルト: 500 | - |
| ExcludeSystem | switch | No | システムデータベースを除外 | - |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- sys.dm_exec_procedure_stats（ストアドプロシージャ統計）
- sys.dm_exec_query_stats（クエリ統計）
- sys.dm_exec_plan_attributes（プラン属性）
- sys.dm_exec_sql_text（SQLテキスト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| ProcName | string | プロシージャ名（アドホック時は空） |
| ObjectID | int | オブジェクトID |
| TypeDesc | string | タイプ（PROCEDURE/STATEMENT） |
| Executions | int | 実行回数 |
| AvgExecMs | int | 平均実行時間（ミリ秒） |
| MaxExecMs | int | 最大実行時間（ミリ秒） |
| CachedTime | datetime | キャッシュ日時 |
| LastExecTime | datetime | 最終実行日時 |
| TotalWorkerTimeMs | int | 総ワーカータイム（ミリ秒） |
| TotalElapsedTimeMs | int | 総経過時間（ミリ秒） |
| SQLText | string | SQLテキスト（50文字+...） |
| FullStatementText | string | 完全なSQLテキスト |

### 出力先

パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQLクエリの構築（begin）
   └─ CTE構築（ストアドプロシージャ + アドホッククエリ）
   └─ フィルタ条件の埋め込み
2. インスタンス接続（process）
3. データベースのフィルタリング
   └─ Database/ExcludeDatabase/ExcludeSystemの適用
4. 各データベースでクエリ実行
5. 結果の出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ構築]
    B --> C{各インスタンスループ}
    C --> D[Connect-DbaInstance]
    D --> E[データベースリスト取得]
    E --> F[フィルタ適用]
    F --> G{各データベースループ}
    G --> H{アクセス可能?}
    H -->|No| I[スキップ警告]
    H -->|Yes| J[クエリ実行]
    J --> K[PSCustomObject構築]
    K --> L[Select-DefaultView]
    L --> G
    I --> G
    G -->|完了| C
    C -->|完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2008以上が必須 | 接続時 |
| BR-002 | デフォルトフィルタ | 100回以上実行、500ms以上の平均実行時間 | デフォルト |
| BR-003 | 結果制限 | データベースごとに最大100件（デフォルト） | 常時 |
| BR-004 | ソート順 | 平均実行時間（AvgExec_ms）の降順 | 常時 |
| BR-005 | アドホックのキャッシュ日時 | '1901-01-01 00:00:00'固定 | STATEMENT型 |

### 計算ロジック

- AvgExec_ms = (total_worker_time / execution_count) / 1000
- MaxExec_ms = max_worker_time / 1000
- TotalWorkerTimeMs = total_worker_time / 1000
- TotalElapsedTimeMs = total_elapsed_time / 1000

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロシージャ統計取得 | sys.dm_exec_procedure_stats | SELECT | ストアドプロシージャ統計 |
| クエリ統計取得 | sys.dm_exec_query_stats | SELECT | アドホッククエリ統計 |
| プラン属性取得 | sys.dm_exec_plan_attributes | SELECT | データベースID取得 |
| SQLテキスト取得 | sys.dm_exec_sql_text | SELECT | SQLテキスト |

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

#### sys.dm_exec_procedure_stats

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | object_id, total_worker_time, execution_count, max_worker_time, cached_time, last_execution_time | database_id = DB_ID() | フィルタ条件適用 |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

フィルタパラメータなしの場合、処理時間が長くなる可能性あり。MaxResultsPerDb、MinExecs、MinExecMsの使用を推奨。

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

- VIEW SERVER STATE権限が必要
- 出力にはSQLテキストが含まれるため、機密情報に注意

## 備考

- デフォルトで100回以上実行された500ms以上のクエリのみを取得
- アドホッククエリのキャッシュ日時は'1901-01-01'固定
- システムデータベースを除外するには-ExcludeSystemを使用

---

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

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

### 推奨読解順序

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

CTEを使用したクエリ構造と出力オブジェクトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | CTEクエリ構造（129-197行目） |

**読解のコツ**: ストアドプロシージャ統計とアドホッククエリ統計をUNIONで結合している点に注目。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | beginブロック（128-214行目） |

**主要処理フロー**:
1. **129-146行目**: ストアドプロシージャ統計のCTE部分
2. **148-149行目**: MinExecs/MinExecMsフィルタの追加
3. **151-173行目**: アドホッククエリ統計のUNION部分
4. **178-197行目**: メインSELECT句の構築

#### Step 3: 実行処理を理解する

processブロックでのデータベースループを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | processブロック（215-275行目） |

**主要処理フロー**:
- **221-239行目**: データベースリストのフィルタリング
- **241-247行目**: アクセス不可データベースのスキップ
- **250-268行目**: クエリ実行と結果の出力

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

```
Get-DbaQueryExecutionTime
    │
    ├─ begin
    │      └─ SQLクエリ構築
    │             ├─ CTE (ストアドプロシージャ)
    │             ├─ UNION (アドホッククエリ)
    │             └─ WHERE/ORDER BY句
    │
    └─ process
           │
           ├─ foreach $instance
           │      │
           │      ├─ Connect-DbaInstance
           │      │      └─ MinimumVersion 10
           │      │
           │      ├─ $server.Databases
           │      │      ├─ Database フィルタ
           │      │      ├─ ExcludeSystem フィルタ
           │      │      └─ ExcludeDatabase フィルタ
           │      │
           │      └─ foreach $db
           │             │
           │             ├─ IsAccessible チェック
           │             │
           │             ├─ ExecuteWithResults
           │             │
           │             └─ PSCustomObject構築
           │
           └─ Select-DefaultView
```

### データフロー図

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

sys.dm_exec_procedure_stats ─▶ CTE (StatsCTE)
                                     │
                                    UNION
                                     │
sys.dm_exec_query_stats ─────▶ CROSS APPLY
sys.dm_exec_plan_attributes ─▶      │
sys.dm_exec_sql_text ────────▶      ▼
                               フィルタ適用
                                     │
                                     ▼
                               TOP N ORDER BY AvgExec_ms DESC
                                     │
                                     ▼
                               PSCustomObject
                                     │
                                     ▼
                               Select-DefaultView
                                     │
                                     ▼
                                  Pipeline
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
