# 通知設計書 15-クエリフィルタ無効

## 概要

本ドキュメントは、sp_BlitzCache ストアドプロシージャにおいて、無効なクエリフィルタが指定された場合に発生するエラー通知の設計書である。

### 本通知の処理概要

本通知は、クエリプランキャッシュ分析の対象をフィルタリングする際に、指定されたフィルタが許可されたリストに含まれていない場合に警告を通知し、デフォルト値にリセットする機能を提供する。

**業務上の目的・背景**：sp_BlitzCacheは、SQL Serverのプランキャッシュを分析するプロシージャである。分析対象を特定の種類のクエリ（ストアドプロシージャ、ステートメント、関数など）に絞り込むことができる。無効なフィルタが指定された場合、ユーザーの意図しない結果が返される可能性があるため、警告を発行しデフォルトの'all'にリセットする。

**通知の送信タイミング**：sp_BlitzCache実行時の初期検証フェーズで、@QueryFilterパラメータの先頭3文字が許可されたフィルタリストに含まれているかを確認する。含まれていない場合に警告が発生する。

**通知の受信者**：sp_BlitzCacheを実行したSQL Serverセッションの呼び出し元。通常はDBA（データベース管理者）や開発者。

**通知内容の概要**：無効なクエリフィルタが指定されたこと、およびデフォルトの'all'にリセットされる旨の警告メッセージを含む。

**期待されるアクション**：受信者は、許可されたクエリフィルタ（all, statement, procedure, function）を確認し、正しい値を@QueryFilterパラメータに指定してsp_BlitzCacheを再実行する。

## 通知種別

SQLメッセージ（RAISERROR）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低（Severity 0） |
| リトライ | なし |

### 送信先決定ロジック

実行中のSQL Serverセッションに対して直接メッセージを送信する。特定の宛先決定ロジックは不要。

## 通知テンプレート

### SQLメッセージの場合

| 項目 | 内容 |
|-----|------|
| Severity | 0 |
| State | 1 |
| WITH NOWAIT | あり |

### 本文テンプレート

```
Invalid query filter chosen. Reverting to all.
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | - |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | - | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_BlitzCache実行 | LEFT(@QueryFilter, 3)が'all', 'sta', 'pro', 'fun'のいずれでもない | パラメータ検証フェーズで発生 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @QueryFilterの先頭3文字が許可リストに含まれる | 正しいフィルタが指定されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_BlitzCache実行] --> B[@QueryFilterを小文字に変換]
    B --> C{LEFT(@QueryFilter, 3)が許可リストに含まれる?}
    C -->|Yes| D[検証OK - 処理継続]
    C -->|No| E[RAISERROR警告発行]
    E --> F[@QueryFilter = 'all'にリセット]
    F --> G[処理継続]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | パラメータ値の検証のみ |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 本通知処理でデータ更新は行わない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| クエリフィルタ無効 | @QueryFilterの先頭3文字が許可リストに含まれない | 許可されたフィルタを使用 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- @QueryFilterはLEFT関数とNOT IN句で固定リストと比較されるため、SQLインジェクションのリスクはない

## 備考

- 許可されるフィルタ: all（全て）, statement（ステートメント）, procedure（プロシージャ）, function（関数）
- 先頭3文字での比較: all, sta, pro, fun
- このエラー発生後も処理は継続され、'all'でフィルタされた結果が返される
- No.14のソート順無効と同様のパターンだが、Severityが0（警告）である点が異なる

---

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

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

### 推奨読解順序

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

sp_BlitzCacheのパラメータ定義と、フィルタ関連のパラメータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | プロシージャのパラメータ定義（@QueryFilter等） |

**読解のコツ**: CREATE PROCEDURE文のパラメータ宣言部分を確認し、@QueryFilterのデフォルト値と許可される値を理解する。

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

クエリフィルタ検証ロジックの開始点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行1187-1193付近のクエリフィルタ検証部分 |

**主要処理フロー**:
1. **行1187**: @QueryFilter = LOWER(@QueryFilter)
2. **行1189**: IF LEFT(@QueryFilter, 3) NOT IN ('all', 'sta', 'pro', 'fun')
3. **行1191**: RAISERRORによる警告メッセージ発行
4. **行1192**: @QueryFilter = 'all'へのリセット

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

```
sp_BlitzCache
    |
    +-- ソート順検証フェーズ（完了後）
    |
    +-- クエリフィルタ検証フェーズ
    |      |
    |      +-- @QueryFilter = LOWER(@QueryFilter)
    |      |
    |      +-- IF LEFT(@QueryFilter, 3) NOT IN (許可リスト)
    |             |
    |             +-- RAISERROR 'Invalid query filter chosen'
    |             |
    |             +-- SET @QueryFilter = 'all'
    |
    +-- 分析実行フェーズ（継続）
```

### データフロー図

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

@QueryFilter ──────────> LOWER()変換 ──────────> LEFT()検証 ──────────> 警告メッセージ
                         |                        |                     |
                         v                        v                     v
                    小文字変換              先頭3文字比較            RAISERROR
                                            NOT IN句               (Severity 0)
                                            |
                                            v
                                       不一致時リセット
                                       @QueryFilter = 'all'
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | プランキャッシュ分析プロシージャ本体 |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | インストールスクリプト | 全スクリプトの一括インストール |
| Install-Azure.sql | `Install-Azure.sql` | インストールスクリプト | Azure用インストールスクリプト |
