# 画面設計書 2-sp_BlitzCache 結果画面

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzCacheストアドプロシージャが出力する、最もリソースを消費するクエリのTop N分析結果画面の設計仕様を記載する。

### 本画面の処理概要

sp_BlitzCache結果画面は、SQL Serverのプランキャッシュを分析し、最もリソースを消費するクエリをランキング形式で表示する画面である。DBAやクエリチューナーが、パフォーマンス改善の対象となるクエリを特定し、問題点を把握するために使用する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題の多くは、特定のクエリのリソース消費に起因する。sp_BlitzCacheは、CPU使用量、読み取り回数、実行時間、メモリグラントなど様々な指標でクエリをソートし、最もリソースを消費するTop Nのクエリを特定する。これにより、DBAはチューニング対象を効率的に絞り込み、限られた時間内で最大の効果を得られる改善を実施できる。さらに、各クエリに対して警告（Warnings）を検出し、パフォーマンス問題の原因を診断する。

**画面へのアクセス方法**：SQL Server Management Studio (SSMS)またはAzure Data Studioなどのクエリツールから、`EXEC sp_BlitzCache`を実行することで結果画面にアクセスする。@SortOrderパラメータで分析指標を指定し、@Topパラメータで取得件数を制御できる。

**主要な操作・処理内容**：
1. dm_exec_query_stats、dm_exec_procedure_stats、dm_exec_trigger_statsからプランキャッシュ情報を取得
2. 指定されたソート順（CPU/Reads/Duration/Executions等）でTop Nクエリを抽出
3. 各クエリプランを分析し、パフォーマンス問題（暗黙的変換、欠落インデックス、パラメータスニッフィング等）を検出
4. 警告情報とともに結果を表示
5. オプションでAI分析（@AI=1）によるチューニングアドバイスを提供

**画面遷移**：
- この画面から遷移できる画面：sp_BlitzIndex診断結果画面（インデックス問題検出時）
- この画面に遷移してくる画面：sp_BlitzFirst診断結果画面（クエリ問題検出時）、sp_Blitz結果画面（パフォーマンス問題検出時）

**権限による表示制御**：クエリプランの取得にはVIEW SERVER STATE権限が必要。sysadmin以外のユーザーでも基本的な分析は可能だが、一部の詳細情報が制限される場合がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | sp_BlitzCache | 主機能 | プランキャッシュを分析し、リソース消費の大きいクエリTop10を表示 |

## 画面種別

一覧（クエリランキング表示）

## URL/ルーティング

```sql
-- 基本実行（CPU順でTop 10）
EXEC sp_BlitzCache;

-- ソート順と件数を指定
EXEC sp_BlitzCache @SortOrder = 'reads', @Top = 20;

-- 特定データベースのみ分析
EXEC sp_BlitzCache @DatabaseName = 'MyDatabase';

-- 特定のクエリハッシュを詳細分析
EXEC sp_BlitzCache @OnlyQueryHashes = '0x1234567890ABCDEF';

-- AI分析を有効化
EXEC sp_BlitzCache @AI = 1;
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|---------|-------------|------|
| @Help | BIT | 0 | 1を指定するとヘルプメッセージを表示 |
| @Top | INT | NULL | 取得するクエリ数（デフォルトは10） |
| @SortOrder | VARCHAR(50) | 'CPU' | ソート順（CPU/Reads/Writes/Duration/Executions/Memory Grant/Spills等） |
| @UseTriggersAnyway | BIT | NULL | トリガーを含めるかどうか |
| @ExportToExcel | BIT | 0 | Excel出力用にフォーマット |
| @ExpertMode | TINYINT | 0 | 詳細モード（0:標準/1:詳細/2:Opserver用） |
| @OutputType | VARCHAR(20) | 'TABLE' | 出力形式 |
| @OutputDatabaseName | NVARCHAR(258) | NULL | 出力先データベース |
| @OutputSchemaName | NVARCHAR(258) | NULL | 出力先スキーマ |
| @OutputTableName | NVARCHAR(258) | NULL | 出力先テーブル |
| @DurationFilter | DECIMAL(38,4) | NULL | 平均実行時間でフィルタ（秒） |
| @HideSummary | BIT | 0 | サマリー結果セットを非表示 |
| @IgnoreSystemDBs | BIT | 1 | システムDB（master,model,msdb,tempdb等）を除外 |
| @OnlyQueryHashes | VARCHAR(MAX) | NULL | 特定のクエリハッシュのみ分析 |
| @IgnoreQueryHashes | VARCHAR(MAX) | NULL | 除外するクエリハッシュ |
| @OnlySqlHandles | VARCHAR(MAX) | NULL | 特定のSQLハンドルのみ分析 |
| @DatabaseName | NVARCHAR(128) | NULL | 特定データベースでフィルタ |
| @StoredProcName | NVARCHAR(128) | NULL | 特定ストアドプロシージャでフィルタ |
| @SlowlySearchPlansFor | NVARCHAR(4000) | NULL | プランテキスト内を検索（%ワイルドカード可） |
| @Reanalyze | BIT | 0 | 既存結果を再分析 |
| @BringThePain | BIT | 0 | 大量データ処理許可 |
| @MinimumExecutionCount | INT | 0 | 最小実行回数でフィルタ |
| @MinutesBack | INT | NULL | 過去N分以内に作成されたプランのみ |
| @AI | TINYINT | 0 | AI分析（1:有効/2:プロンプト生成のみ） |
| @AIModel | VARCHAR(200) | NULL | 使用するAIモデル（デフォルト: gpt-4.1-mini） |
| @AIURL | VARCHAR(200) | NULL | AI APIエンドポイント |
| @Debug | TINYINT | 0 | デバッグモード |

## 表示項目

### 第1結果セット（メイン結果）

| 列名 | データ型 | 説明 |
|-----|---------|------|
| QueryType | NVARCHAR(258) | クエリタイプ（Statement/Stored Procedure/Trigger） |
| DatabaseName | sysname | データベース名 |
| AverageCPU | DECIMAL(38,4) | 平均CPU時間（ms） |
| TotalCPU | DECIMAL(38,4) | 累計CPU時間（ms） |
| PercentCPU | MONEY | CPU使用率（%） |
| AverageDuration | DECIMAL(38,4) | 平均実行時間（ms） |
| TotalDuration | DECIMAL(38,4) | 累計実行時間（ms） |
| AverageReads | BIGINT | 平均読み取り数 |
| TotalReads | BIGINT | 累計読み取り数 |
| ExecutionCount | BIGINT | 実行回数 |
| ExecutionsPerMinute | MONEY | 分あたり実行回数 |
| TotalWrites | BIGINT | 累計書き込み数 |
| PlanCreationTime | DATETIME | プラン作成日時 |
| LastExecutionTime | DATETIME | 最終実行日時 |
| PlanHandle | VARBINARY(64) | プランハンドル |
| SqlHandle | VARBINARY(64) | SQLハンドル |
| QueryHash | BINARY(8) | クエリハッシュ |
| QueryPlanHash | BINARY(8) | クエリプランハッシュ |
| QueryText | NVARCHAR(MAX) | クエリテキスト |
| QueryPlan | XML | 実行プラン |
| Warnings | VARCHAR(MAX) | 検出された警告 |
| MinGrantKB | BIGINT | 最小メモリグラント（KB） |
| MaxGrantKB | BIGINT | 最大メモリグラント（KB） |
| TotalSpills | BIGINT | 累計スピル数 |
| SetOptions | VARCHAR(MAX) | SET オプション |
| Pattern | NVARCHAR(20) | クエリパターン |
| Remove Plan Handle From Cache | 計算列 | DBCC FREEPROCCACHEコマンド |
| SQL Handle More Info | 計算列 | 詳細分析用sp_BlitzCache呼び出し |
| Query Hash More Info | 計算列 | クエリハッシュ別分析用コマンド |

### 第2結果セット（警告サマリー）

| 列名 | データ型 | 説明 |
|-----|---------|------|
| Priority | TINYINT | 優先度 |
| FindingsGroup | VARCHAR(50) | 問題カテゴリ |
| Finding | VARCHAR(500) | 問題名 |
| URL | VARCHAR(200) | 参照URL |
| Details | VARCHAR(4000) | 詳細情報 |

## イベント仕様

### 1-プロシージャ実行

ユーザーがsp_BlitzCacheを実行すると、以下の処理フローが実行される：

1. パラメータの検証とデフォルト値の設定
2. ##BlitzCacheProcs、##BlitzCacheResultsグローバル一時テーブルの準備
3. dm_exec_query_stats等からプランキャッシュ情報を取得
4. 指定されたソート順でTop Nを抽出
5. 各プランを解析し、警告を検出
6. @AI=1の場合、AI APIにクエリとプランを送信しアドバイス取得
7. 結果を返却

### 2-ソート順オプション

| @SortOrder | 説明 |
|-----------|------|
| CPU | CPU使用時間順（デフォルト） |
| Reads | 読み取り数順 |
| Writes | 書き込み数順 |
| Duration | 実行時間順 |
| Executions | 実行回数順 |
| xpm / Executions per minute | 分あたり実行回数順 |
| Memory Grant | メモリグラント順 |
| Unused Grant | 未使用メモリグラント順 |
| Spills | スピル数順 |
| Query Hash | クエリハッシュ順 |
| Duplicate | 重複プラン順 |
| Recent Compilations | 最近のコンパイル順 |
| avg + 上記 | 平均値でソート |

### 3-警告検出項目

sp_BlitzCacheは以下の警告を検出する：

| 警告カテゴリ | 説明 |
|------------|------|
| implicit_conversions | 暗黙的型変換 |
| missing_index_count | 欠落インデックス |
| parameter_sniffing | パラメータスニッフィングの疑い |
| unparameterized_query | パラメータ化されていないクエリ |
| plan_warnings | プラン警告 |
| long_running | 長時間実行 |
| is_forced_plan | 強制プラン |
| is_cursor | カーソル使用 |
| is_parallel | 並列処理 |
| tvf_estimate | テーブル値関数の見積もり問題 |
| compile_timeout | コンパイルタイムアウト |
| warning_no_join_predicate | 結合述語なし |
| is_table_scan | テーブルスキャン |
| is_key_lookup_expensive | 高コストのキー参照 |
| is_big_spills | 大量スピル |
| stale_stats | 古い統計情報 |

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プロシージャ実行 | ##BlitzCacheProcs | INSERT | 分析結果を格納 |
| プロシージャ実行 | ##BlitzCacheResults | INSERT | 警告結果を格納 |
| 出力テーブル指定時 | @OutputTableName | INSERT | 結果を永続テーブルに保存 |

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

#### ##BlitzCacheProcs（グローバル一時テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | SPID | @@SPID | セッション識別 |
| INSERT | QueryType | dm_exec_query_stats等から判定 | Statement/Procedure/Trigger |
| INSERT | DatabaseName | DB_NAME(dbid) | プランキャッシュから取得 |
| INSERT | TotalCPU | total_worker_time / 1000.0 | マイクロ秒からミリ秒に変換 |
| INSERT | TotalReads | total_logical_reads | 論理読み取り数 |
| INSERT | ExecutionCount | execution_count | DMVから直接取得 |
| INSERT | Warnings | 各種フラグから動的生成 | カンマ区切り文字列 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | 情報 | sp_BlitzCache doesn't work on versions of SQL prior to 2008. | SQL Server 2005以前で実行時 |
| - | ヘルプ | (各パラメータの説明) | @Help = 1 で実行時 |

## 例外処理

| 例外状況 | 動作 |
|---------|------|
| SQL Server 2005/2000 | エラーメッセージを表示して終了 |
| プランキャッシュが空 | 空の結果セットを返却 |
| @OnlyQueryHashesの形式不正 | スペースなしCSVリストが必要 |
| @Top > 10 で @SortOrder = 'all' | @BringThePain = 1 が必要 |

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 既知の制限事項：
  - @IgnoreQueryHashesと@OnlyQueryHashesはスペースなしのCSVリストが必要
  - SQL Server 2008R2以前ではトリガー実行カウントが不正確
  - AI機能は単一クエリプランでのみ動作

---

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

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

### 推奨読解順序

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

まず、グローバル一時テーブルの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行38-47: ##BlitzCacheResultsテーブル定義 |
| 1-2 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行49-242: ##BlitzCacheProcsテーブル定義（メイン結果構造） |

**読解のコツ**: ##で始まるグローバル一時テーブルは全セッションから参照可能。SPIDカラムでセッションを識別している。計算列（AS句）の定義に注目すると、出力形式を理解できる。

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

プロシージャのシグネチャとパラメータ処理を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行245-288: ALTER PROCEDUREとパラメータ定義 |
| 2-2 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行295-301: バージョン情報とVersionCheckMode処理 |
| 2-3 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行305-500+: @Help処理とパラメータ説明 |

**主要処理フロー**:
1. **行295**: バージョン設定 `@Version = '8.29', @VersionDate = '20260203'`
2. **行305-500**: @Help = 1の場合、パラメータ説明を表示
3. **行248**: @SortOrderデフォルト値 'CPU'

#### Step 3: ソート順と抽出処理を理解する

@SortOrderに基づくクエリ抽出ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | @SortOrder処理部分（コード後半） |

**主要処理フロー**:
- @SortOrderの値に応じてORDER BY句を動的生成
- 'avg'プレフィックスがある場合は平均値でソート

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

```
sp_BlitzCache
    │
    ├─ パラメータ検証・初期化
    │      ├─ バージョンチェック
    │      ├─ @Help処理
    │      └─ @SortOrder正規化
    │
    ├─ グローバル一時テーブル準備
    │      ├─ ##BlitzCacheProcs
    │      └─ ##BlitzCacheResults
    │
    ├─ プランキャッシュ情報取得
    │      ├─ dm_exec_query_stats
    │      ├─ dm_exec_procedure_stats
    │      └─ dm_exec_trigger_stats
    │
    ├─ Top N抽出・ソート
    │      └─ @SortOrderに基づく順序付け
    │
    ├─ プラン分析・警告検出
    │      ├─ 暗黙的型変換検出
    │      ├─ 欠落インデックス検出
    │      └─ その他警告検出
    │
    ├─ AI分析（@AI=1の場合）
    │      └─ 外部API呼び出し
    │
    └─ 結果出力
           ├─ 第1結果セット（クエリ詳細）
           └─ 第2結果セット（警告サマリー）
```

### データフロー図

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

@パラメータ群 ───────▶ sp_BlitzCache ─────────────────▶ 結果セット1
                           │                              （クエリ詳細）
                           ▼                                   │
    dm_exec_query_stats ──▶ ##BlitzCacheProcs ──────────▶ 結果セット2
    dm_exec_procedure_stats     │                        （警告サマリー）
    dm_exec_trigger_stats       │
    dm_exec_query_plan    ──────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | メインプロシージャ定義 |
