# バッチ設計書 13-sp_BlitzQueryStore

## 概要

本ドキュメントは、sp_BlitzQueryStoreストアドプロシージャのバッチ設計書です。本プロシージャは、SQL ServerのQuery Storeに蓄積されたデータを分析し、リソース集約型のクエリを特定してパフォーマンス問題を検出する非推奨（Deprecated）ストアドプロシージャです。

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

sp_BlitzQueryStoreは、SQL Server 2016以降で利用可能なQuery Store機能のデータを詳細に分析し、最もリソースを消費するクエリを特定するストアドプロシージャです。CPU時間、実行時間、I/O、メモリ使用量などの多角的な観点からクエリパフォーマンスを評価し、パラメータスニッフィングの症状や欠落インデックスなどの問題を検出します。

**業務上の目的・背景**：データベースのパフォーマンス問題を診断する際、Query Storeには豊富な実行統計が蓄積されています。しかし、その生データを直接分析するには専門知識が必要です。本プロシージャは、Query Storeデータを自動分析し、問題のあるクエリとその改善のためのヒントを提供することで、DBAやデベロッパーのパフォーマンスチューニング作業を支援します。現在は非推奨となっています。

**バッチの実行タイミング**：パフォーマンス問題の調査時、または定期的なパフォーマンスレビュー時に手動実行します。

**主要な処理内容**：
1. Query Storeの有効性確認と互換性レベルの検証
2. 指定期間内の実行統計の集計・分析
3. リソース消費量によるクエリのランキング
4. 実行プランの解析と警告の生成
5. パラメータスニッフィング症状の検出
6. 待機統計の分析（SQL Server 2017以降）
7. 欠落インデックス、暗黙の型変換などの問題検出
8. 結果の整形と出力

**前後の処理との関連**：Query Store機能が対象データベースで有効化されている必要があります。sp_BlitzCacheと類似の分析機能を提供しますが、キャッシュではなくQuery Storeを対象とします。

**影響範囲**：読み取り専用の分析処理であり、対象データベースへの書き込みは行いません。一時テーブルを使用して分析結果を蓄積します。

## バッチ種別

診断・分析 / パフォーマンス分析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| SQL Server 2016以降 | Query Store機能のサポートに必要 |
| Azure SQL Database互換性レベル130以上 | Azure環境での実行要件 |
| Query Store有効化 | 対象データベースでQuery Storeが有効 |
| データベースがオンライン | アクセス可能な状態 |
| マルチユーザーアクセス | シングルユーザーモードでは実行不可 |

### 実行可否判定

- SQL Serverバージョンが2016（13.x）以降であること
- Azure SQL Databaseの場合、互換性レベルが130以上であること
- Azure Data Warehouseではないこと
- 指定されたデータベースが存在し、オンライン状態であること
- 対象データベースでQuery Storeが有効化されていること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| @Help | BIT | No | 0 | 1の場合、ヘルプ情報を表示 |
| @DatabaseName | NVARCHAR(128) | Yes* | NULL | 分析対象のデータベース名（*Azure以外では必須） |
| @Top | INT | No | 3 | 各カテゴリで取得する上位クエリ数 |
| @StartDate | DATETIME2 | No | NULL | 分析期間の開始日時（未指定時は過去7日間） |
| @EndDate | DATETIME2 | No | NULL | 分析期間の終了日時（未指定時は過去7日間） |
| @MinimumExecutionCount | INT | No | NULL | 最小実行回数フィルタ |
| @DurationFilter | DECIMAL(38,4) | No | NULL | 平均実行時間フィルタ（秒単位） |
| @StoredProcName | NVARCHAR(128) | No | NULL | 特定ストアドプロシージャに絞って分析 |
| @Failed | BIT | No | 0 | 1の場合、失敗したクエリのみ分析 |
| @PlanIdFilter | INT | No | NULL | 特定のプランIDに絞って分析 |
| @QueryIdFilter | INT | No | NULL | 特定のクエリIDに絞って分析 |
| @ExportToExcel | BIT | No | 0 | 1の場合、Excel出力用にフォーマット |
| @HideSummary | BIT | No | 0 | 1の場合、サマリー結果を非表示 |
| @SkipXML | BIT | No | 0 | 1の場合、XML形式のカラムをスキップ |
| @Debug | BIT | No | 0 | 1の場合、デバッグ情報を出力 |
| @ExpertMode | BIT | No | 0 | 1の場合、追加の高度な分析を実行 |
| @Version | VARCHAR(30) | No | NULL | OUTPUT: バージョン番号を返却 |
| @VersionDate | DATETIME | No | NULL | OUTPUT: バージョン日付を返却 |
| @VersionCheckMode | BIT | No | 0 | 1の場合、バージョン確認のみで終了 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| sys.query_store_query | DB | クエリ情報 |
| sys.query_store_query_text | DB | クエリテキスト |
| sys.query_store_plan | DB | 実行プラン情報 |
| sys.query_store_runtime_stats | DB | 実行時統計 |
| sys.query_store_runtime_stats_interval | DB | 統計の時間区間 |
| sys.query_store_wait_stats | DB | 待機統計（2017以降） |
| sys.query_context_settings | DB | コンテキスト設定 |
| sys.databases | DB | データベース情報 |
| sys.configurations | DB | サーバー構成（CTFP等） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 結果セット1 | Table | サマリー（@HideSummary=0時） |
| 結果セット2 | Table | クエリ詳細分析結果 |
| RAISERRORメッセージ | メッセージ | 進捗・警告情報 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（結果セット出力） |
| 出力先 | SSMSまたはクライアントアプリケーション |
| 文字コード | N/A |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. バージョン・互換性チェック
   └─ SQL Server 2016以降、Azure互換性130以上の確認
2. データベース存在・状態確認
   └─ オンライン状態、Query Store有効化の確認
3. 設定値の取得
   └─ CTFP、min memory per query等
4. 一時テーブル作成
   └─ 分析結果格納用テーブル
5. 集計期間の決定
   └─ @StartDate/@EndDateまたはデフォルト7日間
6. 基本メトリクス収集
   └─ 実行統計、プラン情報の取得
7. 詳細分析実行
   └─ プラン解析、警告生成
8. パラメータスニッフィング検出
   └─ 実行時間のばらつき分析
9. 待機統計分析
   └─ SQL Server 2017以降の場合
10. 結果出力
    └─ サマリーと詳細の出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Help表示?}
    B -->|Yes| C[ヘルプ出力]
    C --> Z[終了]
    B -->|No| D{バージョンチェック}
    D -->|不適合| E[エラー出力]
    E --> Z
    D -->|適合| F{データベース検証}
    F -->|失敗| E
    F -->|成功| G{Query Store有効?}
    G -->|No| E
    G -->|Yes| H[設定値取得]
    H --> I[一時テーブル作成]
    I --> J[集計期間決定]
    J --> K[基本メトリクス収集]
    K --> L[詳細分析実行]
    L --> M[パラメータスニッフィング検出]
    M --> N{待機統計DMV存在?}
    N -->|Yes| O[待機統計分析]
    N -->|No| P[スキップ]
    O --> Q[結果出力]
    P --> Q
    Q --> Z
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定取得 | sys.configurations | SELECT | CTFP、min memory per query |
| DB情報取得 | sys.databases | SELECT | Query Store状態、互換性レベル |
| QS情報取得 | sys.query_store_* | SELECT | Query Store各種DMV |
| 一時データ格納 | #grouped_interval | INSERT | 集計期間データ |
| 一時データ格納 | #working_plans | INSERT | 分析対象プラン |
| 一時データ格納 | #working_metrics | INSERT | メトリクスデータ |
| 一時データ格納 | #working_plan_text | INSERT | プランテキスト |

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

#### 一時テーブル（#working_metrics）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | database_name | 対象DB名 | |
| INSERT | plan_id | sys.query_store_planから | |
| INSERT | query_id | sys.query_store_queryから | |
| INSERT | count_executions | 実行回数 | 集計値 |
| INSERT | avg_duration | 平均実行時間（ms） | |
| INSERT | avg_cpu_time | 平均CPU時間（ms） | |
| INSERT | avg_logical_io_reads | 平均論理読取（MB） | |
| INSERT | avg_query_max_used_memory | 平均メモリ使用量（MB） | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | バージョンエラー | SQL Server 2016未満 | SQL Server 2016以降にアップグレード |
| N/A | 互換性エラー | Azure DB互換性130未満 | 互換性レベルを130以上に変更 |
| N/A | 環境エラー | Azure Data Warehouse | サポート対象外 |
| N/A | パラメータエラー | @DatabaseName未指定 | データベース名を指定 |
| N/A | 存在エラー | 指定DBが存在しない | 正しいデータベース名を指定 |
| N/A | 状態エラー | 指定DBがオフライン | データベースをオンライン化 |
| N/A | 設定エラー | Query Store無効 | Query Storeを有効化 |
| N/A | データなし | Query Storeが有効なDBなし | いずれかのDBでQuery Storeを有効化 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（診断ツールのため） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

エラー発生時はRAISERRORでメッセージが出力されます。読み取り専用の診断ツールであるため、データの整合性に影響はありません。エラー内容に従って前提条件を確認してください。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（READ UNCOMMITTED分離レベル） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | Query Storeデータ量に依存 |
| 目標処理時間 | 数秒〜数分（データ量依存） |
| メモリ使用量上限 | 一時テーブルサイズに依存 |

## 排他制御

- READ UNCOMMITTED分離レベルで実行されるため、ロック競合を最小化
- 他のセッションへの影響なし

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各処理ステップ | Checking database validity, Checking for query_store_wait_stats等 |
| 情報ログ | 状態確認時 | 互換性レベル、DMV存在有無 |
| デバッグログ | @Debug=1時 | 動的SQL、一時テーブルデータ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | 診断ツールのためアラート不要 |

## 備考

- バージョン：8.19（2024-02-22）
- 本プロシージャは非推奨（Deprecated）であり、Deprecatedフォルダに移動済み
- SQL Server 2016以降が必須
- Azure SQL Databaseでは互換性レベル130以上が必要
- Azure Data Warehouseはサポート対象外
- SQL Server 2017以降では追加の待機統計分析が利用可能
- Parameter Sensitive Plan Optimization（SQL Server 2022）の検出をサポート
- @ExpertMode=1で追加の高度な分析（many-to-many merge join、row goal、adaptive join等）を実行
- 実行コストしきい値（CTFP）に近いクエリの検出機能あり
- @DurationFilterは秒単位で指定、内部ではミリ秒に変換
