# 通知設計書 41-BlitzCacheSortorder無効

## 概要

本ドキュメントは、sp_BlitzAnalysisストアドプロシージャにおいて、@BlitzCacheSortorderパラメータに無効なソートオプションが指定された場合に発生するエラー通知の設計を記載する。

### 本通知の処理概要

本通知は、sp_BlitzAnalysisの実行時にクエリ結果のソート順を制御する@BlitzCacheSortorderパラメータに対して、サポートされていない値が指定された場合にエラーメッセージを出力し、処理を中断する機能を提供する。

**業務上の目的・背景**：sp_BlitzAnalysisは、SQL Serverの診断データを分析するためのストアドプロシージャであり、BlitzCacheの結果をどのような基準でソートするかを指定できる。無効なソートオプションが指定された場合、意図しない結果や処理エラーを防ぐため、早期にユーザーに通知し処理を中断する必要がある。これにより、データベース管理者が正しいパラメータ値を使用できるようガイダンスを提供する。

**通知の送信タイミング**：sp_BlitzAnalysisプロシージャの実行開始直後、パラメータ検証フェーズにおいて@BlitzCacheSortorderの値がサポートされているオプションのリスト（'all', 'cpu', 'reads', 'writes', 'duration', 'executions', 'memory grant', 'spills'）に含まれていない場合に送信される。

**通知の受信者**：sp_BlitzAnalysisを実行したSQL Serverクライアントセッション。RAISERRORステートメントによりクライアントに直接エラーメッセージが返される。

**通知内容の概要**：エラーメッセージには、無効なソートオプションが指定されたことと、サポートされている有効な値のリスト（'all', 'cpu', 'reads', 'writes', 'duration', 'executions', 'memory grant', 'spills'）が含まれる。

**期待されるアクション**：ユーザーは通知内容を確認し、@BlitzCacheSortorderパラメータにサポートされている値のいずれかを指定してsp_BlitzAnalysisを再実行する。

## 通知種別

RAISERRORによるSQL Serverエラーメッセージ（クライアント通知）

## 送信仕様

### 基本情報

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

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

sp_BlitzAnalysisを実行したクライアントセッションに対して、RAISERRORステートメントにより直接エラーメッセージを送信する。WITH NOWAITオプションにより即座にメッセージが送信される。

## 通知テンプレート

### エラーメッセージ

| 項目 | 内容 |
|-----|------|
| メッセージレベル | 11 |
| 状態 | 0 |
| 形式 | テキスト |

### 本文テンプレート

```
Invalid sort option specified for @BlitzCacheSortorder, supported values are 'all', 'cpu', 'reads', 'writes', 'duration', 'executions', 'memory grant', 'spills'
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_BlitzAnalysis実行 | @OutputTableNameBlitzCacheがNOT NULLかつ@BlitzCacheSortorderがサポートリストに含まれない場合 | パラメータ検証フェーズで検出 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @BlitzCacheSortorderがNULLの場合 | デフォルト値'cpu'が自動設定されるため検証をスキップ |
| @OutputTableNameBlitzCacheがNULLの場合 | BlitzCacheの出力が不要なため検証をスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_BlitzAnalysis実行開始] --> B{@BlitzCacheSortorderがNULL?}
    B -->|Yes| C[デフォルト値'cpu'を設定]
    B -->|No| D[小文字に変換]
    C --> E{@OutputTableNameBlitzCacheがNOT NULL?}
    D --> E
    E -->|No| F[検証スキップ、処理継続]
    E -->|Yes| G{@BlitzCacheSortorderが有効値リストに含まれる?}
    G -->|Yes| F
    G -->|No| H[RAISERROR実行]
    H --> I[RETURN - 処理中断]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | なし | エラー発生時は即座にRETURNするため更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パラメータ検証エラー | @BlitzCacheSortorderが無効値 | エラーメッセージを出力し処理中断 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（プロシージャ実行時に即時送信）

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

- パラメータ値のみを検証するため、個人情報の漏洩リスクはない
- エラーメッセージにはシステム内部情報は含まれない

## 備考

- @BlitzCacheSortorderパラメータは大文字小文字を区別しない（内部で小文字に変換される）
- デフォルト値は'cpu'であり、NULLが渡された場合は自動的にこの値が設定される

---

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

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

### 推奨読解順序

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

パラメータ定義とサポートされる値のリストを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | @BlitzCacheSortorderパラメータの定義（行24）とデフォルト値を確認 |

**読解のコツ**: T-SQLストアドプロシージャのパラメータ定義は、CREATEまたはALTER PROCEDURE文の直後に記載される。

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

検証ロジックの起点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | パラメータ検証セクション（行117-129） |

**主要処理フロー**:
1. **行118-121**: @BlitzCacheSortorderがNULLの場合、デフォルト値'cpu'を設定
2. **行123**: @BlitzCacheSortorderを小文字に変換
3. **行125**: @OutputTableNameBlitzCacheがNOT NULLの条件チェック
4. **行125-128**: IN句でサポートされる値リストと比較
5. **行127**: 無効な場合、RAISERRORでエラーメッセージ出力
6. **行128**: RETURN文で処理中断

#### Step 3: エラーメッセージ出力処理

RAISERRORステートメントの詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | RAISERROR文の構造（行127） |

**主要処理フロー**:
- **行127**: RAISERROR('Invalid sort option...', 11, 0) WITH NOWAIT
  - 第2引数11: Severity（重大度）- ユーザー定義エラー
  - 第3引数0: State（状態）
  - WITH NOWAIT: 即座にクライアントへ送信

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

```
sp_BlitzAnalysis
    │
    ├─ パラメータ初期化
    │      └─ @BlitzCacheSortorder NULL処理（行118-121）
    │
    ├─ パラメータ検証
    │      ├─ 小文字変換（行123）
    │      └─ 有効値チェック（行125-128）
    │             └─ RAISERROR（行127）
    │
    └─ RETURN（行128）
```

### データフロー図

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

@BlitzCacheSortorder ───▶ NULL判定 ───▶ 小文字変換 ───▶ 有効値リストと比較
      │                                                       │
      │                                                       ▼
      │                                              ┌─────────────────┐
      │                                              │  無効な場合      │
      │                                              │  RAISERROR      │
      │                                              │  + RETURN       │
      │                                              └─────────────────┘
      │                                                       │
      └───────────────────────────────────────────────────────▶ クライアント
                                                        エラーメッセージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | ソース | メインストアドプロシージャ、通知発生元 |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | ソース | 全スクリプトインストーラー（同一ロジック含む） |
| Install-Azure.sql | `Install-Azure.sql` | ソース | Azure用インストーラー（同一ロジック含む） |
