# 通知設計書 53-AI自動設定変更

## 概要

本ドキュメントは、sp_BlitzCache実行時にAI機能（@AI = 1）が有効化されているが、必要なストアドプロシージャ（sp_invoke_external_rest_endpoint）が存在しない場合に発生する警告通知について定義する。

### 本通知の処理概要

sp_BlitzCacheはSQL Serverのクエリプランキャッシュを分析するストアドプロシージャであり、AI機能を使用してクエリプランの改善提案を生成する機能を持つ。@AI = 1（AIサービス呼び出しモード）が指定されているが、Azure SQL Databaseで提供されるsp_invoke_external_rest_endpointプロシージャが存在しない環境では、AIサービスを呼び出すことができない。この場合、自動的に@AI = 2（プロンプト生成のみモード）に変更し、ユーザーに通知する。

**業務上の目的・背景**：sp_BlitzCacheのAI機能は、OpenAI等のAIサービスを呼び出してクエリプランの分析と改善提案を行う。しかし、sp_invoke_external_rest_endpointはAzure SQL Database固有の機能であり、オンプレミスSQL ServerやAzure以外の環境では利用できない。ユーザーが@AI = 1を指定した場合でも、環境制約によりAIサービス呼び出しが不可能な場合は、プロンプト生成のみモード（@AI = 2）にフォールバックすることで、ユーザーが手動でAIサービスを利用できるようにする。

**通知の送信タイミング**：sp_BlitzCache実行時に、@AI = 1が設定されており、かつsys.all_objectsにsp_invoke_external_rest_endpointが存在しない場合。

**通知の受信者**：sp_BlitzCacheを実行したSQL Serverユーザー（DBA、開発者など）。

**通知内容の概要**：@AIが1に設定されていたが、sp_invoke_external_rest_endpointが存在しないためAIサービスを呼び出せないこと、代わりに@AI = 2（プロンプト生成のみ）に変更されたことを通知する。

**期待されるアクション**：ユーザーは生成されたプロンプトをコピーし、ChatGPT等のAIサービスに手動で入力して分析結果を取得するか、Azure SQL Database環境でsp_BlitzCacheを再実行する。

## 通知種別

コンソール出力（RAISERROR WITH NOWAIT）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（RAISERROR WITH NOWAITによる即時出力） |
| 優先度 | 中（警告レベル、重大度0） |
| リトライ | なし |

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

sp_BlitzCacheを実行したセッションのメッセージ出力に直接表示される。

## 通知テンプレート

### コンソール出力

| 項目 | 内容 |
|-----|------|
| 出力方法 | RAISERROR WITH NOWAIT（重大度0、状態1） |
| メッセージタイプ | 情報メッセージ |

### 本文テンプレート

```
@AI was set to 1, but sp_invoke_external_rest_endpoint does not exist here, so we can't call AI services. Setting @AI to 2 instead to just generate prompts.
```

### 添付ファイル

なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ストアドプロシージャ実行 | sp_BlitzCache実行（AI設定時） | @AI = 1 AND NOT EXISTS(SELECT * FROM sys.all_objects WHERE name = 'sp_invoke_external_rest_endpoint') | AI呼び出しモードだが必要なプロシージャが存在しない場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @AI = 0 または @AI IS NULL | AI機能が無効の場合 |
| @AI = 2 | 最初からプロンプト生成のみモードの場合 |
| sp_invoke_external_rest_endpointが存在 | Azure SQL Database等でプロシージャが利用可能な場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_BlitzCache実行] --> B{@AI = 1?}
    B -->|No| Z[通知なし]
    B -->|Yes| C{sp_invoke_external_rest_endpoint<br/>が存在?}
    C -->|Yes| D[AI設定のデフォルト値取得]
    C -->|No| E[SET @AI = 2]
    E --> F[RAISERROR 警告メッセージ]
    F --> G[プロンプト生成のみモードで処理継続]
    D --> H[AIサービス呼び出しモードで処理]
    G --> I[終了]
    H --> I
    Z --> I
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| sys.all_objects | sp_invoke_external_rest_endpointの存在確認 | nameカラムで検索 |

### テーブル別参照項目詳細

#### sys.all_objects

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | オブジェクト名で存在確認 | WHERE name = 'sp_invoke_external_rest_endpoint' |

### 更新テーブル一覧

なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | 本通知は警告であり、自動的にフォールバック | @AI = 2に変更して処理継続 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（sp_BlitzCache実行時に即時出力）

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

- 本通知には機密情報は含まれない
- AIサービス呼び出しにはAzure SQL Databaseのsp_invoke_external_rest_endpointが必要
- AIサービス利用時はDatabase Scoped Credentialによる認証が必要

## 備考

- sp_invoke_external_rest_endpointはAzure SQL Database固有の機能
- @AI = 2モードでは、AIプロンプトが生成されるため、ユーザーは手動でChatGPT等に入力可能
- ソースコードのコメントに「drop-in replacement」の可能性が記載されており、同名のプロシージャを自作すればオンプレミスでも利用可能

---

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

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

### 推奨読解順序

#### Step 1: AI設定チェックロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | AI機能の設定とフォールバックロジック |

**主要処理フロー**:
1. **行911**: AI設定デフォルト値のセットアップ開始（RAISERROR）
2. **行918**: sp_invoke_external_rest_endpointの存在チェック
3. **行923**: @AI = 2への変更
4. **行924**: 警告メッセージの出力（RAISERROR WITH NOWAIT）

**読解のコツ**: このチェックはAI設定の初期化フェーズで行われる。「drop-in replacement」のコメントは、ユーザーが独自実装で代替可能であることを示唆している。

#### Step 2: #ai_configurationテーブルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | AI設定テーブルの構造と参照 |

**主要処理フロー**:
- **行927-938**: @AIModelがNULLの場合、#ai_configurationテーブルからデフォルト設定を取得

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

```
sp_BlitzCache (エントリーポイント)
    │
    ├─ [AI設定セットアップ] RAISERROR('Setting up AI configuration defaults')
    │
    ├─ [条件チェック] @AI = 1?
    │      │
    │      └─ [存在チェック] sys.all_objects WHERE name = 'sp_invoke_external_rest_endpoint'
    │             │
    │             ├─ [存在する] → AI設定読み込み続行
    │             │      └─ #ai_configuration テーブル参照
    │             │
    │             └─ [存在しない]
    │                    ├─ SET @AI = 2
    │                    └─ RAISERROR 警告メッセージ
    │
    └─ [以降のキャッシュ分析処理]
```

### データフロー図

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

@AI = 1 ───────────────▶ [条件評価]
                              │
                              ▼
                    sys.all_objects
                    WHERE name =
                    'sp_invoke_external_rest_endpoint'
                              │
                              ▼
                    ┌─────────┴──────────┐
                    │                    │
                    ▼                    ▼
              [存在する]           [存在しない]
                    │                    │
                    ▼                    ▼
           AIサービス利用可能      @AI = 2に変更
                    │                    │
                    ▼                    ▼
         #ai_configuration参照     RAISERROR警告出力
                    │                    │
                    ▼                    ▼
           AIサービス呼び出し      プロンプト生成のみ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | 本通知を発生させるメインプロシージャ（行918-925） |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | ソース | 全スクリプト一括インストール（行14075-14081に同一ロジック） |
| Install-Azure.sql | `Install-Azure.sql` | ソース | Azure向けインストール（行1810-1816に同一ロジック） |
