# 機能設計書 10-クエリノード

## 概要

本ドキュメントは、Giselleにおけるクエリノード機能の設計を定義する。ベクトルストアに対する類似検索を実行するためのオペレーションノードの型定義とデータ構造を規定する。

### 本機能の処理概要

クエリノードは、ベクトルストアに対して類似検索（セマンティック検索）を実行するオペレーションノードである。RAG（Retrieval-Augmented Generation）パイプラインの検索部分を担当する。

**業務上の目的・背景**：Giselleのワークフローにおいて、ドキュメントや知識ベースから関連情報を検索し、AI生成の入力として活用する必要がある。本機能により、ベクトルストアに保存されたドキュメントチャンクに対して類似検索を実行し、クエリに関連する情報を取得できる。これにより、RAGパターンを活用した高精度なテキスト生成が可能となる。

**機能の利用シーン**：ワークフローエディタ画面でクエリノードを追加・設定する時、ベクトルストアノードと連携して検索を実行する時、テキスト生成の前処理として関連情報を取得する時などに利用される。

**主要な処理内容**：
1. クエリノードの型定義（QueryContent）
2. 検索クエリの指定
3. 検索パラメータの設定（最大結果数、類似度閾値）

**関連システム・外部連携**：ragパッケージによるクエリサービスと連携。PostgreSQL pgvectorによるベクトル検索。

**権限による制御**：ベクトルストアへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 補助機能 | ベクトルストアクエリノードの追加・編集 |

## 機能種別

データ型定義 / ノード構造定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "query" | Yes | ノードコンテンツ種別 | リテラル型 |
| query | string | Yes | 検索クエリ文字列 | 文字列 |
| maxResults | number | No | 最大結果数（デフォルト: 20） | 1-100の整数 |
| similarityThreshold | number | No | 類似度閾値（デフォルト: 0.3） | 0-1の数値 |

### デフォルト値

| パラメータ名 | デフォルト値 | 説明 |
|-------------|-------------|------|
| maxResults | 20 | DEFAULT_MAX_RESULTS定数で定義 |
| similarityThreshold | 0.3 | DEFAULT_SIMILARITY_THRESHOLD定数で定義 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| results | SearchResult[] | 検索結果の配列 |

各SearchResultには以下が含まれる：
- チャンクテキスト
- 類似度スコア
- メタデータ（ソースファイル情報等）

### 出力先

- ワークフロー内の後続ノード（接続経由）

## 処理フロー

### データ構造定義フロー

```
1. デフォルト値の定数定義
   └─ DEFAULT_MAX_RESULTS = 20
   └─ DEFAULT_SIMILARITY_THRESHOLD = 0.3

2. QueryContent定義
   └─ type: "query"固定
   └─ query: 検索クエリ文字列
   └─ maxResults: 最大結果数（オプション、1-100）
   └─ similarityThreshold: 類似度閾値（オプション、0-1）
```

### フローチャート

```mermaid
flowchart TD
    A[QueryContent] --> B[type: "query"]
    A --> C[query: 検索文字列]
    A --> D{maxResults}
    D -->|指定あり| E[1-100の整数]
    D -->|未指定| F[デフォルト: 20]

    A --> G{similarityThreshold}
    G -->|指定あり| H[0-1の数値]
    G -->|未指定| I[デフォルト: 0.3]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 結果数制限 | maxResultsは1-100の範囲 | 常に適用 |
| BR-002 | 類似度範囲 | similarityThresholdは0-1の範囲 | 常に適用 |
| BR-003 | デフォルト適用 | 未指定時はデフォルト値を使用 | パラメータ未指定時 |

### 計算ロジック

特になし（型定義のため）

## データベース操作仕様

本機能は型定義のため、直接のデータベース操作は発生しない。実行時はpgvectorを使用したベクトル類似検索が実行される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | Zodスキーマ検証失敗 | 入力データの確認 |
| RANGE_ERROR | 範囲エラー | maxResults/similarityThresholdが範囲外 | 許容範囲内の値を使用 |

### リトライ仕様

型定義のため該当なし

## トランザクション仕様

型定義のため該当なし

## パフォーマンス要件

型定義のため該当なし（実行時のパフォーマンスはragパッケージで管理）

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

- 検索クエリの内容がログに記録される可能性があるため、機密情報を含まないよう注意
- ベクトルストアへのアクセス権限管理が必要

## 備考

- QueryContentReferenceはノード参照時の軽量版として使用
- 入力としてベクトルストアノードとの接続が必要
- 検索結果はテキスト生成ノードの入力として活用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | query.ts | `packages/protocol/src/node/operations/query.ts` | QueryContent全体構造 |

**読解のコツ**: デフォルト値の定数とZodスキーマのバリデーション設定を確認する。

#### Step 2: QueryContentを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | query.ts | `packages/protocol/src/node/operations/query.ts` | 各フィールドの定義（1-17行目） |

**主要処理フロー**:
- **3行目**: DEFAULT_MAX_RESULTS = 20
- **4行目**: DEFAULT_SIMILARITY_THRESHOLD = 0.3
- **6行目**: type: "query"固定
- **7行目**: query: z.string()（必須）
- **8行目**: maxResults: z.number().int().min(1).max(100).optional()
- **9行目**: similarityThreshold: z.number().min(0).max(1).optional()

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

```
QueryContent (query.ts)
    │
    ├─ type: z.literal("query")
    │
    ├─ query: z.string()
    │
    ├─ maxResults: z.number().int().min(1).max(100).optional()
    │      └─ DEFAULT_MAX_RESULTS = 20
    │
    └─ similarityThreshold: z.number().min(0).max(1).optional()
           └─ DEFAULT_SIMILARITY_THRESHOLD = 0.3
```

### データフロー図

```
[ワークフローエディタ]              [プロトコル層]              [RAG実行]

クエリ設定UI ───▶ QueryContent
    │                     │
    │                     ├─ query ───▶ 検索クエリ
    │                     │
    │                     ├─ maxResults ───▶ 結果数制限
    │                     │
    │                     └─ similarityThreshold ───▶ 類似度フィルタ
    │
    ▼
Workspace.nodes[] ───▶ ストレージ保存
                              │
                              ▼
                       タスク実行時 ───▶ ベクトル検索実行
                              │
                              ▼
                       検索結果 ───▶ 後続ノードへ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| query.ts | `packages/protocol/src/node/operations/query.ts` | ソース | QueryContent定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | QueryNode型、isQueryNode関数 |
| index.ts | `packages/rag/src/query-service/postgres/index.ts` | ソース | 実際のクエリ実行処理 |
| vector-store.ts | `packages/protocol/src/node/variables/vector-store.ts` | ソース | VectorStoreContent定義 |
