# 画面設計書 159-クエリ実行時間

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるクエリ実行時間分析機能の設計を定義する。sys.dm_exec_procedure_statsとsys.dm_exec_query_statsからCPU実行時間の統計を取得し、最も時間のかかるストアドプロシージャとSQLステートメントを特定する。

### 本画面の処理概要

本機能は、SQL Serverの動的管理ビューを照会し、CPUワーカー時間データを基にパフォーマンスボトルネックを特定する。ストアドプロシージャとアドホッククエリの両方を分析対象とする。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題をトラブルシューティングする際、どのクエリやストアドプロシージャが最もCPUリソースを消費しているかを把握することが重要である。本機能は、手動でDMVを照会したり、高コストなプロファイラートレースを実行することなく、平均実行時間、総実行回数、最大実行時間を含む詳細な実行メトリクスを提供する。デフォルトでは、100回以上実行され、平均実行時間が500ms以上のクエリを対象に、データベースごとに上位100件を返す。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaQueryExecutionTime -SqlInstance <インスタンス名>`
- `Get-DbaQueryExecutionTime -SqlInstance <インスタンス名> -Database <データベース名>`

**主要な操作・処理内容**：
1. sys.dm_exec_procedure_statsからストアドプロシージャの実行統計取得
2. sys.dm_exec_query_statsからアドホッククエリの実行統計取得
3. MinExecs/MinExecMsでフィルタリング
4. 平均実行時間でソートしてTop N件を取得
5. SQLテキストと実行メトリクスの結合

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- パイプラインでSelect-Object等と連携可能

**権限による表示制御**：
- SQL Server接続権限が必要
- sys.dm_exec_procedure_stats, sys.dm_exec_query_stats への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 429 | Get-DbaQueryExecutionTime | 主機能 | クエリ実行時間統計の取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaQueryExecutionTime`

## 入出力項目

### Get-DbaQueryExecutionTime パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| 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 | 例外処理の有効化 |

## 表示項目

### Get-DbaQueryExecutionTime 出力プロパティ

| プロパティ名 | 型 | 説明 | デフォルト表示 |
|-------------|------|------|---------------|
| ComputerName | string | コンピュータ名 | Yes |
| InstanceName | string | インスタンス名 | Yes |
| SqlInstance | string | 完全インスタンス名 | Yes |
| Database | string | データベース名 | Yes |
| ProcName | string | プロシージャ名（アドホックの場合は空） | Yes |
| ObjectID | int | オブジェクトID | Yes |
| TypeDesc | string | タイプ（PROCEDURE または STATEMENT） | Yes |
| Executions | long | 総実行回数 | Yes |
| AvgExecMs | decimal | 平均実行時間（ミリ秒） | Yes |
| MaxExecMs | decimal | 最大実行時間（ミリ秒） | Yes |
| CachedTime | datetime | プランキャッシュ日時（アドホックは1901-01-01） | Yes |
| LastExecTime | datetime | 最終実行日時 | Yes |
| TotalWorkerTimeMs | long | 総CPUワーカー時間（ミリ秒） | Yes |
| TotalElapsedTimeMs | long | 総経過時間（ミリ秒） | Yes |
| SQLText | string | SQLテキスト（先頭50文字 + ...） | Yes |
| FullStatementText | string | 完全なSQLテキスト | No |

## イベント仕様

### 1-Get-DbaQueryExecutionTime実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続（最小バージョン: SQL Server 2008）
2. Database/ExcludeDatabase/ExcludeSystemでデータベースをフィルタ
3. 各データベースに対してCTEクエリを実行：
   - sys.dm_exec_procedure_statsからストアドプロシージャ統計を取得
   - sys.dm_exec_query_statsからアドホッククエリ統計を取得
   - UNION ALLで結合
4. MinExecs/MinExecMsでフィルタリング
5. AvgExec_ms DESCでソートしてTOP N件取得
6. Select-DefaultViewでFullStatementTextを非表示に設定

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

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

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

### テーブル別更新項目詳細

本機能は読み取り専用のため、データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Verbose | データベース処理時 | "Processing {db} on {instance}" |
| - | Warning | パラメータなし実行時 | "Results may take time, depending on system resources and size of buffer cache." |
| - | Warning | パラメータなし実行時 | "Consider limiting results using -MaxResultsPerDb, -MinExecs and -MinExecMs parameters." |
| - | Warning | データベースアクセス不可 | "The database {db} is not accessible. Skipping database." |
| - | Error | 接続失敗 | "Failure" |
| - | Error | クエリ失敗 | "Could not process {db} on {instance}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |
| SQL Server 2008未満 | MinimumVersion 10 により自動的にスキップ |
| データベースアクセス不可 | Warning出力後、次のデータベースへ継続 |
| クエリ実行失敗 | Stop-Function実行、次のデータベースへ継続 |

## 備考

- ストアドプロシージャとアドホッククエリの両方を分析
- アドホッククエリのCachedTimeは1901-01-01（プロシージャのみ有効な値）
- SQLTextは先頭50文字 + "..." で省略、FullStatementTextで完全なテキスト取得可能
- ExcludeSystemはmaster, model, msdb, tempdbを除外
- MinExecs/MinExecMsのデフォルト値により、ノイズを除外して真に問題のあるクエリに焦点

---

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

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

### 推奨読解順序

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

クエリ実行時間情報のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | 251-268行目: PSCustomObject出力構造 |

**読解のコツ**: TypeDescがPROCEDUREとSTATEMENTで分かれることに注意。FullStatementTextはデフォルト非表示。

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

処理の起点となるコマンドレット関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | 111-126行目: param()ブロック |

**主要処理フロー**:
1. **128-214行目**: beginブロックでSQLクエリ構築
2. **221-226行目**: Connect-DbaInstance
3. **228-239行目**: データベースフィルタリング
4. **241-273行目**: 各データベースでクエリ実行と結果出力

#### Step 3: SQLクエリ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | 129-146行目: dm_exec_procedure_stats部分 |
| 3-2 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | 151-173行目: dm_exec_query_stats部分 |
| 3-3 | Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | 178-213行目: 結果セレクトとORDER BY |

**主要処理フロー**:
- CTE (StatsCTE) でストアドプロシージャとアドホッククエリをUNION
- MinExecs/MinExecMsでWHERE句構築
- TOP N + ORDER BY AvgExec_ms DESC

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

```
Get-DbaQueryExecutionTime
    |
    +-- begin
    |       +-- $sql クエリ構築
    |           +-- dm_exec_procedure_stats 部分
    |           +-- UNION
    |           +-- dm_exec_query_stats 部分
    |               +-- CROSS APPLY dm_exec_plan_attributes
    |               +-- CROSS APPLY dm_exec_sql_text
    |           +-- WHERE (MinExecs, MinExecMs)
    |           +-- ORDER BY AvgExec_ms DESC
    |
    +-- process
            |
            +-- Connect-DbaInstance (MinimumVersion 10)
            |
            +-- foreach ($db in $dbs)
                    |
                    +-- [IsAccessible = false] -> Warning, continue
                    |
                    +-- db.ExecuteWithResults($sql)
                    |
                    +-- foreach ($row in results)
                            |
                            +-- PSCustomObject 作成
                            |
                            +-- Select-DefaultView -ExcludeProperty FullStatementText
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance  ----+
                                                 |
SqlCredential  ------>                           |
                                                 v
Database       ------>  フィルタリング  ----+
ExcludeDatabase -----+                       |
ExcludeSystem -------+                       |
                                             v
MinExecs       ------>  WHERE句構築         CTEクエリ実行
MinExecMs      ------>                           |
                                                 v
MaxResultsPerDb -----> TOP N                dm_exec_procedure_stats
                                                 |
                                            UNION
                                                 |
                                            dm_exec_query_stats
                                            + dm_exec_plan_attributes
                                            + dm_exec_sql_text
                                                 |
                                                 v
                                            ORDER BY AvgExec_ms DESC
                                                 |
                                                 v
                                            PSCustomObject
                                            (TypeDesc: PROCEDURE/STATEMENT)
                                                 |
                                                 v
                                            Select-DefaultView
                                            (FullStatementText非表示)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaQueryExecutionTime.ps1 | `public/Get-DbaQueryExecutionTime.ps1` | ソース | クエリ実行時間分析の主処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
