# 機能設計書 34-union_all

## 概要

本ドキュメントは、dplyrパッケージの `union_all()` 関数の機能設計を記述する。この関数は2つのデータフレームの和集合を取得し、重複を保持する集合演算関数である。

### 本機能の処理概要

`union_all()` は、2つのデータフレーム x と y のすべての行を結合し、重複をそのまま保持した新しいデータフレームを返す関数である。SQLの UNION ALL 演算に相当する操作を提供する。

**業務上の目的・背景**：データ分析において、複数のデータソースを完全に統合し、重複も含めた全レコードを保持する必要がある場面がある。例えば、トランザクションログの統合、イベントデータの時系列結合、複数期間のデータを重複を含めて分析する場合などに使用される。`union()` とは異なり、重複除去のオーバーヘッドがないため、重複が許容される場合や存在しないことが分かっている場合に効率的である。

**機能の利用シーン**：
- 複数のログファイルからのデータ統合
- 時系列データの期間別結合
- 重複を許容するデータの垂直結合
- bind_rowsの代替（互換性チェック付き）

**主要な処理内容**：
1. `check_dots_empty()` で追加引数がないことを確認
2. `check_compatible()` で2つのデータフレームの互換性を検証
3. `vctrs::vec_rbind()` を使用して行を結合（重複保持）
4. `dplyr_reconstruct()` で元のデータフレーム型を保持

**関連システム・外部連携**：vctrパッケージの `vec_rbind()` に依存。

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、GUI画面は存在しない |

## 機能種別

データ操作 / 集合演算

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | data.frame | Yes | 最初のデータフレーム | データフレームである必要がある |
| y | data.frame | Yes | 2番目のデータフレーム | xと互換性のあるデータフレームである必要がある |
| ... | (空) | No | 使用されない。空であることが必須 | check_dots_empty()でチェック |

### 入力データソース

プログラムからの直接入力（データフレームオブジェクト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (返り値) | data.frame | xとyのすべての行を含むデータフレーム。重複行は保持される。型はxを継承する |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. ドット引数の検証
   └─ check_dots_empty()で追加引数がないことを確認

2. 互換性チェック
   └─ check_compatible()でxとyの列名・型の互換性を検証

3. 行の結合
   └─ vec_rbind()でxとyの行を結合
   └─ 重複行は保持される

4. 型の再構築
   └─ dplyr_reconstruct()でxの型を保持

5. 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[check_dots_empty]
    B --> C[check_compatible x, y]
    C --> D{互換性あり?}
    D -->|No| E[エラー: 互換性なし]
    D -->|Yes| F[vec_rbind x, y]
    F --> G[dplyr_reconstruct]
    G --> H[結果を返却]
    H --> I[終了]
    E --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-01 | 互換性要件 | xとyは同じ列名（順序は異なっても可）と互換性のある型を持つ必要がある | 常時 |
| BR-34-02 | 重複保持 | x, yの重複行は結果にそのまま含まれる | 常時 |
| BR-34-03 | 型の継承 | 出力データフレームはxの型を継承する | 常時 |
| BR-34-04 | 行順序 | 出力の行順序はxの行が先、yの行が後 | 常時 |

### 計算ロジック

単純な行の連結: 結果 = xの全行 + yの全行

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

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

該当なし（インメモリ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 互換性エラー | yがデータフレームでない場合 | データフレームを渡す |
| - | 列数不一致エラー | xとyの列数が異なる場合 | 同じ列数のデータフレームを使用 |
| - | 列名不一致エラー | xとyの列名が一致しない場合 | 同じ列名を持つデータフレームを使用 |
| - | 型不一致エラー | 同名の列で型が互換性を持たない場合 | 型を揃えてから実行 |
| - | ドット引数エラー | ...に引数が渡された場合 | 追加引数を削除 |

### リトライ仕様

該当なし（同期処理）

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

該当なし（インメモリ操作）

## パフォーマンス要件

特に定義なし。vctrパッケージの最適化された実装に依存。`union()` より効率的（重複チェックなし）。

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

特になし

## 備考

- `union()` とは異なり、重複行を除去しない
- `bind_rows()` に似ているが、事前に互換性チェックが行われる
- デフォルトメソッドは `vec_c()` を使用してベクター向け動作を提供
- 大量データの結合時は `union()` より高速

---

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

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

### 推奨読解順序

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

互換性チェックのロジックを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sets.R | `R/sets.R` | is_compatible関数（162-241行目）の互換性チェックロジック |

**読解のコツ**: `union_all()` は `union()` と同じ互換性チェックを行うが、結合処理が異なる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sets.R | `R/sets.R` | union_all.data.frame メソッド（123-129行目） |

**主要処理フロー**:
1. **124行目**: `check_dots_empty()` で追加引数がないことを確認
2. **125行目**: `check_compatible(x, y)` で互換性を検証
3. **127行目**: `vec_rbind(x, y)` で行を結合
4. **128行目**: `dplyr_reconstruct(out, x)` で型を保持

#### Step 3: unionとの比較

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sets.R | `R/sets.R` | union.data.frame（113-120行目）との違い |

**比較ポイント**:
- `union()`: `vec_set_union()` を使用（重複除去）
- `union_all()`: `vec_rbind()` を使用（重複保持）

#### Step 4: デフォルトメソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sets.R | `R/sets.R` | union_all.default（71-74行目） |

**主要処理フロー**:
- **73行目**: `vec_c(x, y)` でベクターを結合

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

```
union_all(x, y, ...)
    │
    ├─ union_all.data.frame()     [dplyr]
    │      │
    │      ├─ check_dots_empty()  [rlang]
    │      │
    │      ├─ check_compatible()  [dplyr]
    │      │      │
    │      │      └─ is_compatible()
    │      │
    │      ├─ vec_rbind()         [vctrs]
    │      │
    │      └─ dplyr_reconstruct() [dplyr]
    │
    └─ union_all.default()        [dplyr] (ベクター用)
           │
           └─ vec_c()             [vctrs]
```

### データフロー図

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

データフレーム x ─┐
                  │
                  ├───▶ union_all() ───▶ 結合されたデータフレーム
                  │     (vec_rbind)         (重複あり)
データフレーム y ─┘

例:
x = {A, B, C}
y = {C, D, E}
結果 = {A, B, C, C, D, E}  ← Cが2回出現
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sets.R | `R/sets.R` | ソース | union_all.data.frame、union_all.default実装 |
| grouped-df.R | `R/grouped-df.R` | ソース | dplyr_reconstruct関数 |
