# バッチ設計書 2-sp_BlitzCache

## 概要

本ドキュメントは、SQL Server First Responder Kitに含まれるsp_BlitzCacheストアドプロシージャのバッチ設計書です。sp_BlitzCacheはプランキャッシュ内のリソース集約型クエリを分析し、パフォーマンス問題を検出する診断ツールです。

### 本バッチの処理概要

sp_BlitzCacheは、SQL Serverのプランキャッシュに格納されたクエリプランを分析し、CPU、読み取り、書き込み、実行時間などのリソース消費が多いクエリを特定してパフォーマンス改善のポイントを提示するストアドプロシージャです。

**業務上の目的・背景**：SQL Serverのパフォーマンスチューニングにおいて、最もリソースを消費するクエリを特定することは最優先事項です。sp_BlitzCacheは、プランキャッシュからトップN件のリソース集約型クエリを抽出し、各クエリの実行計画を分析して、パラメータスニッフィング、暗黙的変換、インデックス欠落などの一般的なパフォーマンス問題を自動検出します。これにより、DBAは効率的にチューニング対象を絞り込むことができます。

**バッチの実行タイミング**：随時実行（手動）。パフォーマンス問題が発生した際のトラブルシューティング、または定期的なパフォーマンス監査として実行されます。sp_BlitzFirstと連携して定期的にテーブルに出力することも可能です。

**主要な処理内容**：
1. dm_exec_query_stats、dm_exec_procedure_stats、dm_exec_trigger_statsからクエリ統計を取得
2. 指定されたソート順（CPU、Reads、Duration等）でトップN件を抽出
3. 各クエリの実行計画XMLを解析
4. パフォーマンス問題パターン（欠落インデックス、暗黙的変換、並列処理問題等）を検出
5. AI分析機能（オプション）によるアドバイス生成
6. 結果の出力（テーブル/画面）

**前後の処理との関連**：sp_BlitzFirstから呼び出されることが多く、リアルタイム診断の一部として使用されます。sp_BlitzIndexと組み合わせてインデックス問題を深掘りすることも一般的です。

**影響範囲**：読み取り専用の診断ツールですが、プランキャッシュの解析は一定のCPUリソースを消費します。大規模なプランキャッシュを持つ環境では、@Top値を制限することが推奨されます。

## バッチ種別

診断・分析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動/sp_BlitzFirstから呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| SQL Serverバージョン | SQL Server 2008以降（2005/2000は非対応） |
| 必要権限 | VIEW SERVER STATE権限 |
| 依存オブジェクト | なし（単体で動作可能） |

### 実行可否判定

- SQL Server 2008より前のバージョンでは、エラーメッセージを出力して終了
- グローバル一時テーブル（##BlitzCacheProcs、##BlitzCacheResults）が使用される

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| @Help | BIT | No | 0 | ヘルプメッセージを表示 |
| @Top | INT | No | NULL | 取得するクエリ件数（NULLの場合はデフォルト動作） |
| @SortOrder | VARCHAR(50) | No | 'CPU' | ソート順（CPU/Reads/Writes/Duration/Executions等） |
| @UseTriggersAnyway | BIT | No | NULL | トリガー統計を含めるか（2008R2以前用） |
| @ExportToExcel | BIT | No | 0 | Excel出力用に整形 |
| @ExpertMode | TINYINT | No | 0 | 詳細モード（0=通常/1=詳細/2=Opserver用） |
| @OutputType | VARCHAR(20) | No | 'TABLE' | 出力形式（TABLE/NONE） |
| @OutputServerName | NVARCHAR(258) | No | NULL | 出力先サーバー名 |
| @OutputDatabaseName | NVARCHAR(258) | No | NULL | 出力先データベース名 |
| @OutputSchemaName | NVARCHAR(258) | No | NULL | 出力先スキーマ名 |
| @OutputTableName | NVARCHAR(258) | No | NULL | 出力先テーブル名 |
| @ConfigurationDatabaseName | NVARCHAR(128) | No | NULL | 構成データベース名 |
| @ConfigurationSchemaName | NVARCHAR(258) | No | NULL | 構成スキーマ名 |
| @ConfigurationTableName | NVARCHAR(258) | No | NULL | 構成テーブル名 |
| @DurationFilter | DECIMAL(38,4) | No | NULL | 平均実行時間（秒）のフィルタ |
| @HideSummary | BIT | No | 0 | サマリー結果を非表示 |
| @IgnoreSystemDBs | BIT | No | 1 | システムDBを除外 |
| @IgnoreReadableReplicaDBs | BIT | No | 1 | 読み取り可能レプリカDBを除外 |
| @OnlyQueryHashes | VARCHAR(MAX) | No | NULL | 特定のクエリハッシュのみ抽出 |
| @IgnoreQueryHashes | VARCHAR(MAX) | No | NULL | 除外するクエリハッシュ |
| @OnlySqlHandles | VARCHAR(MAX) | No | NULL | 特定のSQLハンドルのみ抽出 |
| @IgnoreSqlHandles | VARCHAR(MAX) | No | NULL | 除外するSQLハンドル |
| @QueryFilter | VARCHAR(10) | No | 'ALL' | フィルタ（ALL/procedures/statements/functions） |
| @DatabaseName | NVARCHAR(128) | No | NULL | 特定データベースにフィルタ |
| @StoredProcName | NVARCHAR(128) | No | NULL | 特定ストアドプロシージャにフィルタ |
| @SlowlySearchPlansFor | NVARCHAR(4000) | No | NULL | プランテキスト内を検索 |
| @Reanalyze | BIT | No | 0 | 既存結果を再分析 |
| @SkipAnalysis | BIT | No | 0 | 分析をスキップ |
| @BringThePain | BIT | No | 0 | 詳細分析を有効化 |
| @MinimumExecutionCount | INT | No | 0 | 最小実行回数フィルタ |
| @Debug | TINYINT | No | 0 | デバッグモード（0/1/2） |
| @CheckDateOverride | DATETIMEOFFSET | No | NULL | チェック日時オーバーライド |
| @MinutesBack | INT | No | NULL | 過去N分のプランのみ分析 |
| @AI | TINYINT | No | 0 | AI分析（1=有効、2=プロンプト生成のみ） |
| @AIModel | VARCHAR(200) | No | NULL | AIモデル名 |
| @AIURL | VARCHAR(200) | No | NULL | AI APIエンドポイント |
| @AICredential | VARCHAR(200) | No | NULL | AI認証情報 |
| @AIConfig | NVARCHAR(500) | No | NULL | AI設定テーブル |
| @Version | VARCHAR(30) | No | NULL | バージョン番号（OUTPUT） |
| @VersionDate | DATETIME | No | NULL | バージョン日付（OUTPUT） |
| @VersionCheckMode | BIT | No | 0 | バージョンチェックモード |
| @KeepCRLF | BIT | No | 0 | 改行を保持 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| sys.dm_exec_query_stats | DMV | クエリ実行統計 |
| sys.dm_exec_procedure_stats | DMV | ストアドプロシージャ実行統計 |
| sys.dm_exec_trigger_stats | DMV | トリガー実行統計 |
| sys.dm_exec_query_plan | DMF | クエリ実行計画 |
| sys.dm_exec_sql_text | DMF | クエリテキスト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ##BlitzCacheResults | グローバル一時テーブル | 検出された問題のサマリー |
| ##BlitzCacheProcs | グローバル一時テーブル | 詳細なクエリ統計 |
| 指定テーブル | DB | @OutputTableName指定時に永続化 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（テーブル出力） |
| 出力先 | @OutputDatabaseName.@OutputSchemaName.@OutputTableName |
| 文字コード | UTF-16（SQL Server標準） |
| 区切り文字 | 該当なし |

##BlitzCacheProcsの主要カラム:
- QueryType, DatabaseName, AverageCPU, TotalCPU, PercentCPU
- AverageReads, TotalReads, AverageDuration, TotalDuration
- ExecutionCount, QueryText, QueryPlan
- 各種警告フラグ（is_parallel, implicit_conversions, missing_index_count等）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証とセッション設定
   └─ バージョンチェック、グローバル一時テーブル初期化
2. DMVからクエリ統計を取得
   └─ dm_exec_query_stats等から@SortOrder順にTOP @Top件
3. クエリプランの取得
   └─ dm_exec_query_plan、dm_exec_sql_textの結合
4. プラン分析
   └─ XMLパース、警告フラグの設定
5. 問題パターン検出
   └─ 欠落インデックス、暗黙的変換、パラメータスニッフィング等
6. AI分析（オプション）
   └─ @AI=1の場合、外部API呼び出し
7. 結果出力
   └─ グローバル一時テーブルまたは指定テーブルへ
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{バージョンチェック}
    B -->|2008以降| C[一時テーブル初期化]
    B -->|2005以前| D[エラー終了]
    C --> E[クエリ統計取得]
    E --> F[プラン取得]
    F --> G[プラン分析]
    G --> H[問題パターン検出]
    H --> I{AI分析?}
    I -->|Yes| J[AI API呼び出し]
    I -->|No| K[結果集約]
    J --> K
    K --> L{出力先判定}
    L -->|TABLE| M[画面出力]
    L -->|NONE| N[テーブル出力]
    M & N --> O[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 統計取得 | sys.dm_exec_query_stats | SELECT | クエリ統計の取得 |
| プラン取得 | sys.dm_exec_query_plan | SELECT | 実行計画XMLの取得 |
| 結果格納 | ##BlitzCacheProcs | INSERT | 分析結果の格納 |
| 結果格納 | ##BlitzCacheResults | INSERT | サマリー結果の格納 |
| 永続化 | @OutputTableName | INSERT | 結果の永続化 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | 全カラム | DMVからの分析結果 | 200以上のカラムを持つ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バージョンエラー | SQL Server 2005/2000 | サポートバージョンにアップグレード |
| - | 権限エラー | VIEW SERVER STATE権限なし | 権限を付与 |
| - | タイムアウト | 大規模プランキャッシュ | @Topを小さくして再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライ機能なし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

- タイムアウト時は@Topパラメータを小さい値に設定して再実行
- メモリ不足時は@BringThePain=0で実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | READ UNCOMMITTEDで実行 |
| コミットタイミング | 明示的なトランザクション管理なし |
| ロールバック条件 | 該当なし（読み取り専用） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | @Top件（デフォルト:環境依存） |
| 目標処理時間 | 数秒〜数十秒（プランキャッシュ規模による） |
| メモリ使用量上限 | プランキャッシュサイズに依存 |

## 排他制御

- 読み取り専用のため排他制御は不要
- グローバル一時テーブルはSPIDで分離されるが、同一セッションでの並行実行は非推奨

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | @Debug=1時 | 処理開始メッセージ |
| 進捗ログ | @Debug=1時 | 各処理ステップの状況 |
| 終了ログ | @Debug=1時 | 処理完了メッセージ |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 環境依存 | 該当なし |
| エラー件数 | 0件 | 該当なし |

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 詳細情報: http://FirstResponderKit.org
- 特記事項:
  - @SortOrder='all'で全ソート順を分析可能（@BringThePain=1が必要な場合あり）
  - AI機能はOpenAI API等との連携が必要
  - グローバル一時テーブル##BlitzCacheProcs、##BlitzCacheResultsを使用
