# 機能設計書 5-クエリビルダ

## 概要

本ドキュメントは、Laravel Frameworkのクエリビルダ機能について、その設計思想、処理フロー、および実装詳細を記述したものである。流暢なインターフェースでSQLクエリを構築する機能設計を定義する。

### 本機能の処理概要

クエリビルダは、SQLクエリを直接書くことなく、メソッドチェーンでデータベースクエリを構築できる機能である。SELECT、INSERT、UPDATE、DELETE等の操作を直感的なAPIで提供し、SQLインジェクション対策も自動的に行う。

**業務上の目的・背景**：生SQLの記述はSQLインジェクションのリスクがあり、また可読性・保守性に課題がある。クエリビルダは、型安全でセキュアなクエリ構築を提供し、開発効率とコード品質を向上させる。また、データベース間の互換性を吸収し、異なるDBMSへの移行を容易にする。

**機能の利用シーン**：
- データの検索・絞り込み（WHERE句の構築）
- テーブル結合（JOIN）
- 集計処理（GROUP BY、集約関数）
- ページネーション
- サブクエリの構築
- バルクインサート/アップデート

**主要な処理内容**：
1. SELECT/INSERT/UPDATE/DELETEクエリの構築
2. WHERE句の動的構築（条件演算子、Like、In等）
3. JOIN句の構築
4. ORDER BY/GROUP BY/HAVINGの設定
5. LIMIT/OFFSETの設定
6. バインディング管理（SQLインジェクション対策）
7. サブクエリのサポート

**関連システム・外部連携**：
- Connection（クエリ実行）
- Grammar（SQL文法変換）
- Processor（結果処理）
- Paginator（ページネーション）

**権限による制御**：クエリビルダ自体は権限制御を行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | クエリコンポーネント | 補助機能 | 実行されたSQLクエリの表示連携 |

## 機能種別

データアクセス / クエリ構築 / SQL生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| table | string\|Expression | Yes | 対象テーブル名 | - |
| columns | array | No | 取得カラム（デフォルト: *） | - |
| conditions | array | No | WHERE条件 | - |

### 入力データソース

- アプリケーションコード（メソッドチェーン）
- Eloquent Builder（委譲）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | Collection/stdClass/int/bool | クエリ実行結果 |

### 出力先

- アプリケーションコード（結果セット）
- データベース（INSERT/UPDATE/DELETE時）

## 処理フロー

### 処理シーケンス

```
1. Builder生成
   └─ Connection::table()またはDB::table()で生成
2. クエリ構築
   └─ メソッドチェーンでwhere/join/orderBy等を追加
3. SQL生成
   └─ Grammar::compileSelect()等でSQL文字列生成
4. バインディング準備
   └─ getBindings()でプレースホルダ値を取得
5. クエリ実行
   └─ Connection::select()/insert()/update()/delete()
6. 結果処理
   └─ Processor::processSelect()等で結果を整形
```

### フローチャート

```mermaid
flowchart TD
    A[DB::table('users')] --> B[Builder生成]
    B --> C[where/select/join等]
    C --> D{実行メソッド?}
    D -->|get()| E[Grammar::compileSelect()]
    D -->|insert()| F[Grammar::compileInsert()]
    D -->|update()| G[Grammar::compileUpdate()]
    D -->|delete()| H[Grammar::compileDelete()]
    E --> I[getBindings()]
    F --> I
    G --> I
    H --> I
    I --> J[Connection::実行]
    J --> K[Processor::処理]
    K --> L[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バインディング順序 | select, from, join, where, groupBy, having, order, union, unionOrder | クエリ構築時 |
| BR-02 | 自動エスケープ | 全てのユーザー入力はプレースホルダでバインド | where等での値指定時 |
| BR-03 | NULL判定 | whereNull()/whereNotNull()を使用 | NULLチェック時 |
| BR-04 | カラム参照 | whereColumn()を使用してSQL注入を防止 | カラム間比較時 |

### 計算ロジック

- count(): `SELECT COUNT(*) ...`
- sum($column): `SELECT SUM($column) ...`
- avg($column): `SELECT AVG($column) ...`
- max($column): `SELECT MAX($column) ...`
- min($column): `SELECT MIN($column) ...`

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

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| get() | 指定テーブル | SELECT | データ取得 |
| first() | 指定テーブル | SELECT | 1件取得 |
| insert() | 指定テーブル | INSERT | データ挿入 |
| update() | 指定テーブル | UPDATE | データ更新 |
| delete() | 指定テーブル | DELETE | データ削除 |
| upsert() | 指定テーブル | INSERT/UPDATE | アップサート |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | QueryException | SQL実行エラー | SQLを確認 |
| - | InvalidArgumentException | 無効な演算子 | operators配列を確認 |
| - | LogicException | 無効なクエリ構造 | メソッド呼び出し順序確認 |

### リトライ仕様

デッドロック時のリトライはConnectionレベルで実装。

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

クエリビルダ自体はトランザクションを管理しない。Connection/DBファサードのtransaction()を使用。

## パフォーマンス要件

- 大量データ取得時はchunk()/cursor()を使用
- 不要なカラムはselect()で限定
- インデックスを考慮したwhere条件

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

- プレースホルダバインディングによるSQLインジェクション対策
- whereRaw()使用時は手動でのエスケープが必要
- カラム名はエスケープされないため、ユーザー入力を直接使用しない

## 備考

- Macroable traitでメソッド拡張可能
- toSql()でSQLプレビュー可能
- dd()でクエリとバインディングを確認可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BuilderContract.php | `src/Illuminate/Contracts/Database/Query/Builder.php` | クエリビルダのインターフェース |

**読解のコツ**: Builderが持つ状態（columns, wheres, joins等）のプロパティ構造を先に理解すること。

#### Step 2: クエリビルダ本体を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Builder.php | `src/Illuminate/Database/Query/Builder.php` | クエリビルダ本体 |

**主要処理フロー**:
- **79-89行目**: bindings配列の構造（select, from, join, where等）
- **276-284行目**: コンストラクタ（connection, grammar, processor注入）
- **292-309行目**: select()でカラム設定
- **wheres配列への追加**: where(), orWhere(), whereIn()等
- **joins配列への追加**: join(), leftJoin(), rightJoin()等
- **get()メソッド**: runSelect()でクエリ実行

#### Step 3: Grammarを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Grammar.php | `src/Illuminate/Database/Query/Grammars/Grammar.php` | SQL生成の基底クラス |

**読解ポイント**:
- compileSelect(): SELECT文全体の組み立て
- compileColumns(): カラム句の生成
- compileWheres(): WHERE句の生成
- compileJoins(): JOIN句の生成

#### Step 4: 各DBのGrammarを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MySqlGrammar.php | `src/Illuminate/Database/Query/Grammars/MySqlGrammar.php` | MySQL固有の文法 |
| 4-2 | PostgresGrammar.php | `src/Illuminate/Database/Query/Grammars/PostgresGrammar.php` | PostgreSQL固有の文法 |

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

```
DB::table('users')
    │
    └─ Connection::table($table)
           │
           └─ new Builder($connection, $grammar, $processor)
                  │
                  ├─ select($columns)
                  │      └─ columns[] に追加
                  │
                  ├─ where($column, $operator, $value)
                  │      ├─ wheres[] に追加
                  │      └─ bindings['where'][] にvalue追加
                  │
                  ├─ join($table, $first, $operator, $second)
                  │      └─ joins[] に追加
                  │
                  ├─ orderBy($column, $direction)
                  │      └─ orders[] に追加
                  │
                  └─ get()
                         │
                         ├─ runSelect()
                         │      │
                         │      ├─ toSql()
                         │      │      └─ grammar->compileSelect($this)
                         │      │             ├─ compileColumns()
                         │      │             ├─ compileFrom()
                         │      │             ├─ compileWheres()
                         │      │             ├─ compileJoins()
                         │      │             └─ compileOrders()
                         │      │
                         │      ├─ getBindings()
                         │      │
                         │      └─ connection->select($sql, $bindings)
                         │
                         └─ processor->processSelect($this, $results)
```

### データフロー図

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

テーブル名 ────────────▶ Builder ──────────────────────▶ Collection/stdClass
where条件                    │
joinテーブル                 │
                             ▼
                        Grammar
                             │
                             ▼
                        SQL文字列 + バインディング
                             │
                             ▼
                        Connection::select/insert/update/delete
                             │
                             ▼
                        PDO::prepare + execute ────────▶ DBMS
                             │
                             ▼
                        Processor ──────────────────────▶ 結果セット
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Builder.php | `src/Illuminate/Database/Query/Builder.php` | ソース | クエリビルダ本体 |
| Grammar.php | `src/Illuminate/Database/Query/Grammars/Grammar.php` | ソース | SQL生成基底クラス |
| MySqlGrammar.php | `src/Illuminate/Database/Query/Grammars/MySqlGrammar.php` | ソース | MySQL文法 |
| PostgresGrammar.php | `src/Illuminate/Database/Query/Grammars/PostgresGrammar.php` | ソース | PostgreSQL文法 |
| SQLiteGrammar.php | `src/Illuminate/Database/Query/Grammars/SQLiteGrammar.php` | ソース | SQLite文法 |
| SqlServerGrammar.php | `src/Illuminate/Database/Query/Grammars/SqlServerGrammar.php` | ソース | SQL Server文法 |
| Processor.php | `src/Illuminate/Database/Query/Processors/Processor.php` | ソース | 結果処理基底クラス |
| JoinClause.php | `src/Illuminate/Database/Query/JoinClause.php` | ソース | JOIN句表現 |
| Expression.php | `src/Illuminate/Database/Query/Expression.php` | ソース | 生SQL式 |
| IndexHint.php | `src/Illuminate/Database/Query/IndexHint.php` | ソース | インデックスヒント |
| BuildsQueries.php | `src/Illuminate/Database/Concerns/BuildsQueries.php` | ソース | クエリ構築トレイト |
