# 帳票設計書 2-sp_BlitzCache

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzCacheストアドプロシージャが出力するクエリパフォーマンス分析帳票の設計を記述する。

### 本帳票の処理概要

sp_BlitzCacheは、プランキャッシュから最もリソースを消費しているクエリを分析し、パフォーマンス問題を特定するストアドプロシージャである。CPU使用量、読み取り回数、書き込み回数、実行時間、実行回数、メモリグラント、スピルなど、様々な観点でクエリをランキングし、パフォーマンス改善のための詳細な情報を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題の多くは、非効率なクエリに起因する。本帳票は、DBAやアプリケーション開発者がリソースを最も消費しているクエリを特定し、チューニングの優先順位を決定することを支援する。また、クエリプランの分析により、インデックス不足、暗黙的な型変換、パラメータスニッフィングなどの問題を検出する。

**帳票の利用シーン**：
- 日常的なパフォーマンス監視
- パフォーマンス問題発生時の原因クエリ特定
- アプリケーションリリース後のクエリ評価
- インデックス設計の見直し
- クエリチューニングの効果測定

**主要な出力内容**：
1. QueryType（クエリ種別）：ストアドプロシージャ/ステートメント/トリガー
2. DatabaseName（データベース名）：クエリが属するデータベース
3. TotalCPU/AverageCPU：CPU使用量（合計/平均）
4. TotalReads/AverageReads：読み取り回数（合計/平均）
5. TotalDuration/AverageDuration：実行時間（合計/平均）
6. ExecutionCount：実行回数
7. QueryText（クエリテキスト）：実際のSQLクエリ
8. QueryPlan（実行プラン）：XML形式の実行プラン
9. Warnings（警告）：検出されたパフォーマンス問題

**帳票の出力タイミング**：
- ストアドプロシージャ `EXEC sp_BlitzCache` の手動実行時
- sp_BlitzFirstからの自動呼び出し時
- SQL Server Agentジョブによる定期実行時

**帳票の利用者**：
- データベース管理者（DBA）
- アプリケーション開発者
- パフォーマンスエンジニア
- システムアーキテクト

## 帳票種別

クエリ分析レポート / パフォーマンス分析表

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | SQL Server Management Studio | N/A | `EXEC sp_BlitzCache` 実行 |
| N/A | Azure Data Studio | N/A | `EXEC sp_BlitzCache` 実行 |
| N/A | コマンドライン | sqlcmd | スクリプト実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | TABLE / NONE |
| 用紙サイズ | N/A（結果セットとして出力） |
| 向き | N/A |
| ファイル名 | N/A（テーブル出力時は@OutputTableName指定） |
| 出力方法 | 結果セット返却 / テーブル書き込み |
| 文字コード | NVARCHAR（Unicode） |

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

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

## 帳票レイアウト

### レイアウト概要

結果は2つの結果セットで構成される：サマリー（警告一覧）とクエリ詳細。

```
┌─────────────────────────────────────────────────────────────────────┐
│  結果セット1: サマリー（警告一覧）                                   │
├─────────────────────────────────────────────────────────────────────┤
│  Priority | FindingsGroup | Finding | URL | Details                 │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│  結果セット2: クエリ詳細                                            │
├─────────────────────────────────────────────────────────────────────┤
│  QueryType | DatabaseName | TotalCPU | TotalReads | QueryText | ... │
└─────────────────────────────────────────────────────────────────────┘
```

### 出力カラム詳細（主要項目）

| No | 項目名 | 説明 | データ型 | 表示形式 |
|----|-------|------|----------|---------|
| 1 | QueryType | クエリ種別 | NVARCHAR(258) | テキスト |
| 2 | DatabaseName | データベース名 | SYSNAME | テキスト |
| 3 | AverageCPU | 平均CPU（ミリ秒） | DECIMAL(38,4) | 数値 |
| 4 | TotalCPU | 合計CPU（ミリ秒） | DECIMAL(38,4) | 数値 |
| 5 | PercentCPU | CPU使用率 | MONEY | パーセント |
| 6 | AverageReads | 平均読み取り回数 | BIGINT | 数値 |
| 7 | TotalReads | 合計読み取り回数 | BIGINT | 数値 |
| 8 | ExecutionCount | 実行回数 | BIGINT | 数値 |
| 9 | TotalDuration | 合計実行時間 | DECIMAL(38,4) | 数値 |
| 10 | QueryText | クエリテキスト | NVARCHAR(MAX) | テキスト |
| 11 | QueryPlan | 実行プラン | XML | XML |
| 12 | PlanHandle | プランハンドル | VARBINARY(64) | バイナリ |
| 13 | SqlHandle | SQLハンドル | VARBINARY(64) | バイナリ |
| 14 | QueryHash | クエリハッシュ | BINARY(8) | バイナリ |
| 15 | Warnings | 警告メッセージ | VARCHAR(MAX) | テキスト |
| 16 | MinGrantKB | 最小メモリグラント | BIGINT | 数値 |
| 17 | MaxGrantKB | 最大メモリグラント | BIGINT | 数値 |
| 18 | TotalSpills | 合計スピル回数 | BIGINT | 数値 |
| 19 | missing_indexes | 不足インデックス情報 | XML | XML |
| 20 | implicit_conversion_info | 暗黙的変換情報 | XML | XML |

## 出力条件

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @Help | BIT | 0 | 1でヘルプ表示 |
| @Top | INT | NULL | 取得件数（NULL時は10） |
| @SortOrder | VARCHAR(50) | 'CPU' | ソート順 |
| @ExpertMode | TINYINT | 0 | 詳細モード（0/1/2） |
| @OutputType | VARCHAR(20) | 'TABLE' | 出力形式 |
| @DatabaseName | NVARCHAR(128) | NULL | 対象データベース |
| @StoredProcName | NVARCHAR(128) | NULL | 対象ストアドプロシージャ |
| @DurationFilter | DECIMAL(38,4) | NULL | 最小実行時間フィルタ |
| @IgnoreSystemDBs | BIT | 1 | システムDB除外 |
| @OnlyQueryHashes | VARCHAR(MAX) | NULL | 特定クエリハッシュのみ |
| @IgnoreQueryHashes | VARCHAR(MAX) | NULL | 除外クエリハッシュ |
| @OnlySqlHandles | VARCHAR(MAX) | NULL | 特定SQLハンドルのみ |
| @MinimumExecutionCount | INT | 0 | 最小実行回数 |
| @MinutesBack | INT | NULL | 何分前まで分析 |
| @SlowlySearchPlansFor | NVARCHAR(4000) | NULL | プラン内テキスト検索 |
| @BringThePain | BIT | 0 | 詳細分析有効化 |
| @AI | TINYINT | 0 | AI分析機能（1=有効） |
| @AIModel | VARCHAR(200) | NULL | AIモデル指定 |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | @SortOrderで指定された項目 | 降順 |

### 改ページ条件

結果セットのため改ページなし。@Topパラメータで件数制御。

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

### 参照DMV一覧

| DMV名 | 用途 | 結合条件 |
|-------|------|---------|
| sys.dm_exec_query_stats | クエリ統計情報 | plan_handle |
| sys.dm_exec_procedure_stats | プロシージャ統計 | plan_handle |
| sys.dm_exec_trigger_stats | トリガー統計 | plan_handle |
| sys.dm_exec_sql_text | SQLテキスト取得 | sql_handle |
| sys.dm_exec_query_plan | 実行プラン取得 | plan_handle |
| sys.dm_exec_cached_plans | キャッシュプラン情報 | plan_handle |

### テーブル別参照項目詳細

#### sys.dm_exec_query_stats

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| total_worker_time | TotalCPU | - | マイクロ秒を変換 |
| total_logical_reads | TotalReads | - | - |
| total_logical_writes | TotalWrites | - | - |
| total_elapsed_time | TotalDuration | - | マイクロ秒を変換 |
| execution_count | ExecutionCount | - | - |
| max_grant_kb | MaxGrantKB | - | SQL 2016以降 |
| max_spills | MaxSpills | - | SQL 2016以降 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| AverageCPU | TotalCPU / ExecutionCount | 小数点以下4桁 | |
| AverageReads | TotalReads / ExecutionCount | 切り捨て | |
| AverageDuration | TotalDuration / ExecutionCount | 小数点以下4桁 | |
| PercentCPU | (TotalCPU / 合計CPU) * 100 | 小数点以下2桁 | |
| ExecutionsPerMinute | ExecutionCount / age_minutes | 小数点以下2桁 | |
| PercentMemoryGrantUsed | UsedGrant / MaxGrant * 100 | 小数点以下2桁 | |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[sp_BlitzCache実行] --> B{@Help = 1?}
    B -->|Yes| C[パラメータヘルプ表示]
    B -->|No| D[##BlitzCacheProcs作成]
    D --> E[クエリ統計取得]
    E --> F{@QueryFilter判定}
    F -->|procedures| G[dm_exec_procedure_statsから取得]
    F -->|statements| H[dm_exec_query_statsから取得]
    F -->|all| I[全DMVから取得]
    G --> J[データを##BlitzCacheProcsに挿入]
    H --> J
    I --> J
    J --> K[実行プラン分析]
    K --> L[警告フラグ設定]
    L --> M[不足インデックス抽出]
    M --> N[暗黙的変換検出]
    N --> O{@OutputTableName?}
    O -->|Yes| P[テーブルに出力]
    O -->|No| Q[結果セット返却]
    P --> R[終了]
    Q --> R
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| バージョン非対応 | SQL Server 2008未満 | Sorry, sp_BlitzCache doesn't work on versions of SQL prior to 2008 | サポートバージョンへアップグレード |
| 大量データ警告 | @Top > 10 かつ @SortOrder = 'all' | @BringThePain = 1 が必要 | @BringThePainを設定 |
| 無効なソートオーダー | 不正な@SortOrder値 | ソート可能な値一覧を表示 | 有効な値を指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 10〜1000件（@Top指定） |
| 目標出力時間 | 60秒以内（@Top=10） |
| 同時出力数上限 | 制限なし |

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

- VIEW SERVER STATE権限が必要
- クエリテキストには機密情報が含まれる可能性あり
- 出力テーブルへのアクセス制御が必要
- AI機能使用時は外部サービスへの通信が発生

## 備考

- バージョン: 8.29（2026年2月3日リリース）
- ライセンス: MIT License
- 公式サイト: http://FirstResponderKit.org
- AI機能はgpt-4.1-miniをデフォルトで使用

---

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

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

### 推奨読解順序

#### 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カラムでセッション分離している点に注意。

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

処理の起点となるストアドプロシージャのシグネチャとパラメータを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行245-288: ALTER PROCEDUREとパラメータ定義 |

**主要処理フロー**:
1. **行295**: バージョン情報の設定
2. **行305-500**: @Help=1の場合のパラメータヘルプ出力
3. **行245-288**: 30以上の入力パラメータ定義

#### Step 3: ソートオーダー処理を理解する

様々なソートオプションの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行360-362: SortOrderパラメータの説明 |

**主要処理フロー**:
- CPU, Reads, Writes, Duration, Executions等のソート実装
- Average/Avgプレフィックスで平均値ソート
- xpm（executions per minute）のソート

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

```
sp_BlitzCache (エントリーポイント)
    │
    ├─ パラメータヘルプ表示 (@Help = 1)
    │
    ├─ グローバル一時テーブル作成
    │      ├─ ##BlitzCacheResults
    │      └─ ##BlitzCacheProcs
    │
    ├─ クエリ統計収集
    │      ├─ sys.dm_exec_query_stats
    │      ├─ sys.dm_exec_procedure_stats
    │      └─ sys.dm_exec_trigger_stats
    │
    ├─ 実行プラン分析
    │      ├─ sys.dm_exec_query_plan
    │      ├─ 不足インデックス検出
    │      ├─ 暗黙的変換検出
    │      └─ 警告フラグ設定
    │
    ├─ AI分析（@AI = 1時）
    │      └─ 外部AI API呼び出し
    │
    └─ 結果出力
           ├─ サマリー結果セット
           └─ クエリ詳細結果セット
```

### データフロー図

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

パラメータ指定 ──────────▶ sp_BlitzCache ──────▶ ##BlitzCacheResults
                               │                        │
dm_exec_query_stats ◀──────────┤                        ├──▶ サマリー結果
dm_exec_procedure_stats ◀──────┤                        │
dm_exec_trigger_stats ◀────────┤                        ├──▶ クエリ詳細結果
dm_exec_query_plan ◀───────────┤                        │
dm_exec_sql_text ◀─────────────┘                        └──▶ 出力テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | メインストアドプロシージャ |
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | sp_BlitzCacheを呼び出す |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | スクリプト | 全スクリプトのインストール |
