# 通知設計書 86-AIプロンプト構築

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzCache.sqlにおける「AIプロンプト構築」通知の設計を定義する。この通知は、クエリプラン分析においてAI（人工知能）によるアドバイス生成のためのプロンプト構築処理の開始を示す情報メッセージである。

### 本通知の処理概要

この通知は、sp_BlitzCacheストアドプロシージャがクエリプラン分析結果に基づいてAIへのプロンプトを構築する処理の開始を示す。@AIパラメータが1以上に設定されている場合にのみ、この処理が実行される。

**業務上の目的・背景**：SQL Server 2022以降とAzure SQL Databaseでは、外部REST APIを呼び出す機能（sp_invoke_external_rest_endpoint）が利用可能になった。この機能を活用して、OpenAIやGoogle GeminiなどのLLM（大規模言語モデル）にクエリプランとパフォーマンスメトリクスを送信し、クエリ最適化のアドバイスを自動生成することが可能になった。この通知は、AI分析のためのプロンプト構築が開始されたことをユーザーに通知する。

**通知の送信タイミング**：sp_BlitzCacheプロシージャの実行中、@AI >= 1の場合に、AIプロンプト構築処理が開始される直前のタイミングで送信される。具体的には、各データベースのCONSTITUTION.md拡張プロパティの読み込みと、クエリメトリクス情報のプロンプト生成の前である。

**通知の受信者**：この通知はRAISERROR関数によりSQL Server Management Studio（SSMS）のメッセージウィンドウ、またはsqlcmdなどのコマンドラインツールの標準出力に表示される。主な受信者は、sp_BlitzCacheを@AI=1で実行しているDBA、データベース開発者、システム管理者である。

**通知内容の概要**：「Building AI prompts for query plans」という英語メッセージが表示され、現在AIプロンプトの構築処理を実行中であることを示す。これにより、AI分析の準備段階が開始されたことを把握できる。

**期待されるアクション**：通知の受信者は、AI分析の準備が進行していることを確認し、処理完了を待つ。この後、AIエンドポイントへの呼び出しが行われ、最終的にai_adviceカラムにAIからのアドバイスが格納される。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（WITH NOWAITオプションにより即座に出力） |
| 優先度 | 低（情報レベル、重大度0） |
| リトライ | なし（単発の情報メッセージ） |

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

sp_BlitzCacheを実行しているセッションのクライアント接続に対して直接出力される。送信先の動的な決定ロジックは存在せず、実行元のセッションに対して常に通知される。

## 通知テンプレート

### メール通知の場合

該当なし（コンソール出力のみ）

### 本文テンプレート

```
Building AI prompts for query plans
```

### 添付ファイル

該当なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| プロシージャ実行 | sp_BlitzCache内のAIプロンプト構築開始 | @AI >= 1 | AI機能が有効な場合のみ通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| @AI = 0または未指定 | AI機能が無効の場合は通知されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[警告サマリー処理完了] --> B{@AI >= 1?}
    B -->|No| I[スキップ]
    B -->|Yes| C[RAISERROR実行]
    C --> D[メッセージ即時出力]
    D --> E[#ai_constitution一時テーブル作成]
    E --> F[各DBのCONSTITUTION.md読み込み]
    F --> G[ai_promptカラム更新]
    G --> H[メトリクス情報をプロンプトに追加]
    H --> J[AIエンドポイント呼び出しへ]
    I --> J
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| ##BlitzCacheProcs | プランキャッシュ分析結果の格納 | グローバル一時テーブル |
| sys.extended_properties | CONSTITUTION.md拡張プロパティの取得 | 各データベース |
| #ai_constitution | 拡張プロパティの一時格納 | ローカル一時テーブル |

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

#### ##BlitzCacheProcs

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| DatabaseName | 対象データベース名 | DISTINCT, WHERE QueryPlan IS NOT NULL |
| QueryPlan | クエリプランXML | ai_promptに含める |
| QueryText | クエリテキスト | ai_promptに含める |
| TotalCPU, AverageCPU等 | パフォーマンスメトリクス | ai_promptに含める |
| Warnings | sp_BlitzCache警告 | ai_promptに含める |
| ai_prompt | AIプロンプト文字列 | SET句で更新 |

#### sys.extended_properties

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| value | CONSTITUTION.mdの内容 | WHERE name = 'CONSTITUTION.md' AND class = 0 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| ##BlitzCacheProcs | UPDATE | ai_promptカラムにプロンプト文字列を設定 |
| #ai_constitution | INSERT | 各DBのCONSTITUTION.md内容を挿入 |

#### ##BlitzCacheProcs更新

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| UPDATE | ai_prompt | 構築されたプロンプト文字列 | メトリクス、クエリ、プランを含む |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 拡張プロパティ読み取りエラー | DBへのアクセス権限なし | TRY-CATCHでスキップ |
| メモリ不足 | 大量のプロンプト生成時 | @Topパラメータで対象を制限 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- 通知内容自体に機密情報は含まれない
- AIプロンプトにはクエリテキストとパフォーマンスメトリクスが含まれる
- 外部AIサービスへの送信時はデータの機密性を考慮する必要がある
- VIEW SERVER STATE権限が必要（sp_BlitzCache実行の前提条件）
- CONSTITUTION.md拡張プロパティでAI分析のガイドラインを定義可能

## 備考

- この通知はsp_BlitzCacheのAI機能の一部であり、@AI >= 1の場合にのみ表示される
- WITH NOWAITオプションにより、バッファリングなしで即座にクライアントに送信される
- 重大度0は情報メッセージを意味し、エラーではない
- Azure SQL DBの場合、クロスデータベースアクセスが制限されるため、現在のデータベースのみCONSTITUTION.mdを読み込む
- プロンプトには以下の情報が含まれる：CPU・Duration・I/Oメトリクス、メモリグラント、スピル情報、プラン情報、クエリテキスト、XMLプラン

---

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

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

### 推奨読解順序

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

まず、プロシージャで使用される一時テーブルとAI関連カラムの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | ##BlitzCacheProcsテーブルのai_prompt、ai_advice、ai_raw_response、ai_payloadカラム定義を確認 |
| 1-2 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | #ai_constitution一時テーブルの構造を確認 |

**読解のコツ**: ai_promptはNVARCHAR(MAX)型で、クエリメトリクス・テキスト・XMLプランを含む長い文字列が格納される。

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

処理の起点となる条件分岐を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | @AI >= 1による条件分岐とプロンプト構築処理の開始 |

**主要処理フロー**:
1. **行5118**: IF @AI >= 1 による条件分岐
2. **行5120**: RAISERROR('Building AI prompts for query plans', 0, 1) WITH NOWAITでメッセージ出力
3. **行5124-5201**: CONSTITUTION.md拡張プロパティの読み込み処理
4. **行5203-5310**: ai_promptカラムへのメトリクス情報設定

#### Step 3: プロンプト構築処理を理解する

AIプロンプトの実際の構築ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | CONSTITUTION.mdの読み込みとプロンプトへの組み込み |
| 3-2 | sp_BlitzCache.sql | `sp_BlitzCache.sql` | メトリクス情報のフォーマットとプロンプトへの追加 |

**主要処理フロー**:
- **行5127-5131**: #ai_constitution一時テーブル作成
- **行5140-5201**: 各データベースからCONSTITUTION.md読み込み（カーソル使用）
- **行5214-5280**: メトリクス情報をai_promptカラムに設定（CPU、Duration、I/O、メモリ、スピル等）

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

```
sp_BlitzCache
    |
    +-- [前処理] 警告サマリー処理
    |
    +-- IF @AI >= 1
            |
            +-- RAISERROR('Building AI prompts for query plans')  <-- 本通知
                    |
                    +-- CREATE TABLE #ai_constitution
                    |
                    +-- CURSOR ai_db_cursor (各DBループ)
                    |       |
                    |       +-- TRY-CATCH
                    |               |
                    |               +-- sys.extended_propertiesからCONSTITUTION.md取得
                    |               |
                    |               +-- INSERT INTO #ai_constitution
                    |
                    +-- UPDATE ##BlitzCacheProcs SET ai_prompt (CONSTITUTION.md追加)
                    |
                    +-- UPDATE ##BlitzCacheProcs SET ai_prompt (メトリクス追加)
                    |
                    +-- [後続処理] AIエンドポイント呼び出し
```

### データフロー図

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

sys.extended_properties    --> CONSTITUTION.md読み込み         --> #ai_constitution
(各データベース)

##BlitzCacheProcs          --> プロンプト構築                   --> ##BlitzCacheProcs.ai_prompt
- QueryText                     |                                  (構築されたプロンプト)
- QueryPlan                     v
- TotalCPU/AverageCPU      メトリクスフォーマット
- TotalDuration/...              |
- TotalReads/...                 v
- Warnings                  文字列結合
                                 |
                                 v
                           コンソール出力 <-- RAISERROR
                           "Building AI prompts for query plans"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | AIプロンプト構築処理を含むメインストアドプロシージャ |
