# 通知設計書 14-ソート順無効

## 概要

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

### 本通知の処理概要

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

**業務上の目的・背景**：sp_BlitzCacheは、SQL Serverのプランキャッシュを分析し、問題のあるクエリを特定するプロシージャである。分析結果は様々な観点（CPU使用率、読み取り回数、実行時間など）でソートできる。無効なソート順が指定された場合、ユーザーの意図しない結果が返される可能性があるため、警告を発行しデフォルトのソート順（cpu）にリセットする。

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

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

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

**期待されるアクション**：受信者は、許可されたソート順（cpu, reads, duration, executionsなど）を確認し、正しい値を@SortOrderパラメータに指定してsp_BlitzCacheを再実行する。

## 通知種別

SQLメッセージ（RAISERROR）

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
Invalid sort order chosen, reverting to cpu
```

### 添付ファイル

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

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_BlitzCache実行 | @SortOrderが許可リストに含まれない | パラメータ検証フェーズで発生 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @SortOrderが許可リストに含まれる | 正しいソート順が指定されている場合 |

## 処理フロー

### 送信フロー

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

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ソート順無効 | @SortOrderが許可リストに含まれない | 許可されたソート順を使用 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし

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

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

## 備考

- 許可されるソート順: cpu, avg cpu, reads, avg reads, writes, avg writes, duration, avg duration, executions, avg executions, compiles, memory grant, avg memory grant, unused grant, spills, avg spills, all, all avg, sp_BlitzIndex, query hash, duplicate
- このエラー発生後も処理は継続され、'cpu'でソートされた結果が返される

---

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

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

### 推奨読解順序

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

sp_BlitzCacheのパラメータ定義と、ソート関連のパラメータを理解する。

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

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

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

ソート順検証ロジックの開始点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | 行1176-1185付近のソート順検証部分 |

**主要処理フロー**:
1. **行1176**: RAISERRORによるデバッグメッセージ「Checking sort order」
2. **行1177-1181**: @SortOrderのIN句による許可リスト検証
3. **行1183**: RAISERRORによるエラーメッセージ発行
4. **行1184**: @SortOrder = 'cpu'へのリセット

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

```
sp_BlitzCache
    |
    +-- パラメータ前処理フェーズ
    |      |
    |      +-- @SortOrder = LOWER(@SortOrder)
    |      |
    |      +-- 別名変換（duplicates -> duplicate等）
    |
    +-- ソート順検証フェーズ
    |      |
    |      +-- RAISERROR 'Checking sort order'
    |      |
    |      +-- IF @SortOrder NOT IN (許可リスト)
    |             |
    |             +-- RAISERROR 'Invalid sort order chosen'
    |             |
    |             +-- SET @SortOrder = 'cpu'
    |
    +-- 分析実行フェーズ（継続）
```

### データフロー図

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

@SortOrder ──────────> LOWER()変換 ──────────> IN句検証 ──────────> エラーメッセージ
                       |                        |                    |
                       v                        v                    v
                  小文字変換              許可リスト比較           RAISERROR
                                          |                      (Severity 16)
                                          v
                                     不一致時リセット
                                     @SortOrder = 'cpu'
```

### 関連ファイル一覧

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