# 機能設計書 92-Polarsプラグイン

## 概要

本ドキュメントはNushellのPolarsプラグイン（nu_plugin_polars）について記述する。大規模データフレーム処理を可能にするプラグインの設計を定義する。

### 本機能の処理概要

Polarsプラグインは、Rustで実装された高性能データフレームライブラリ「Polars」をNushellから利用できるようにするプラグインである。DataFrame、LazyFrame、Expression等のカスタム値型を提供し、大規模データの効率的な処理を実現する。

**業務上の目的・背景**：データ分析やETL処理において、Nushellの標準テーブル操作だけでは処理速度やメモリ効率が不十分な場合がある。PolarsプラグインはArrow形式のメモリレイアウトを活用し、高速なデータ処理を提供することで、大規模データ分析のユースケースに対応する。

**機能の利用シーン**：
- CSVやParquetファイルから大規模データを読み込む際
- 数百万行以上のデータに対してフィルタリング・集計を行う際
- 複数データソースの結合（join）処理を行う際
- データの遅延評価（Lazy Evaluation）による最適化が必要な際
- 統計分析や時系列データ処理を行う際

**主要な処理内容**：
1. データフレームの作成・読み込み（polars open, polars into-df）
2. カラム選択・フィルタリング（polars select, polars filter）
3. グループ化と集計（polars group-by, polars agg）
4. データフレームの結合（polars join）
5. 遅延評価による最適化（polars lazy, polars collect）
6. 各種フォーマットへの保存（polars save）

**関連システム・外部連携**：Polarsライブラリ（Rust）、Arrow形式データ、Parquet/CSV/JSON/Avro等のファイルフォーマット

**権限による制御**：特になし。ファイルアクセスは通常のファイルシステム権限に従う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIコマンドとして提供され、特定の画面とは関連しない |

## 機能種別

データ処理 / 変換処理 / 集計処理 / ファイル入出力

## 入力仕様

### 入力パラメータ

#### polars open

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| file | String | Yes | 読み込むファイルのパス | 存在するファイルパス |
| --type | String | No | ファイルタイプ（csv, parquet, json等） | サポート形式 |
| --lazy | Switch | No | LazyFrameとして読み込む | - |

#### polars into-df

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | PipelineData | Yes | 変換元データ | テーブル形式データ |
| --schema | Record | No | スキーマ定義 | 有効なスキーマ |

#### polars select

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| columns | Expression... | Yes | 選択するカラム/式 | 有効な式 |

#### polars filter

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| predicate | Expression | Yes | フィルタ条件式 | Boolean式 |

#### polars group-by

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| columns | Expression... | Yes | グループ化キー | 有効な式 |

### 入力データソース

- ファイル: CSV, Parquet, JSON, NDJSON, Arrow IPC, Avro
- Nushellテーブル/リスト: パイプライン入力
- カスタム値: NuDataFrame, NuLazyFrame, NuExpression等

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| NuDataFrame | CustomValue | 即時評価データフレーム |
| NuLazyFrame | CustomValue | 遅延評価データフレーム |
| NuExpression | CustomValue | 式（計算定義） |
| NuLazyGroupBy | CustomValue | 遅延グループ化オブジェクト |
| NuWhen | CustomValue | 条件分岐式 |
| NuSchema | CustomValue | スキーマ定義 |
| NuDataType | CustomValue | データ型定義 |
| NuSelector | CustomValue | カラムセレクタ |

### 出力先

- パイプライン出力: カスタム値またはNushellテーブル（polars into-nu使用時）
- ファイル: polars saveコマンドによる各種フォーマット出力

## 処理フロー

### 処理シーケンス

```
データ読み込み:
1. polars open でファイル読み込み
   └─ ファイルタイプを判定し適切なリーダーを選択
2. Arrow形式でメモリにロード
   └─ 列指向フォーマットで効率的にデータ保持
3. NuDataFrameまたはNuLazyFrameとして返却
   └─ キャッシュに登録

遅延評価パイプライン:
1. polars lazy でLazyFrameに変換
2. 各種操作（select, filter, group-by等）を適用
   └─ 実際の計算は行わず、計算グラフを構築
3. polars collect で評価を実行
   └─ Polarsオプティマイザが計算を最適化して実行

カスタム値管理:
1. 各カスタム値にUUIDを付与
2. プラグインのCacheに保存
3. custom_value_droppedでキャッシュから削除
```

### フローチャート

```mermaid
flowchart TD
    A[polars open] --> B{LazyMode?}
    B -->|Yes| C[NuLazyFrame作成]
    B -->|No| D[NuDataFrame作成]
    C --> E[計算グラフ構築]
    D --> F[即時処理]
    E --> G[polars collect]
    G --> H[最適化実行]
    F --> I[結果出力]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-92-01 | 遅延評価優先 | 大規模データは遅延評価を推奨 | データサイズが大きい場合 |
| BR-92-02 | スキーマ推論 | 明示的スキーマがない場合は自動推論 | ファイル読み込み時 |
| BR-92-03 | カスタム値キャッシュ | カスタム値はプラグインキャッシュに保持 | 全てのカスタム値生成時 |
| BR-92-04 | GC連携 | プラグインGCを無効化可能 | 長時間処理時 |

### 計算ロジック

- 集計関数: sum, mean, min, max, std, var, median, quantile等
- 文字列操作: str-lengths, str-replace, str-contains等
- 日時操作: get-year, get-month, get-day, strftime等
- 条件式: when-then-otherwise構文

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

本機能はデータベースを使用しない。インメモリでのデータフレーム操作を行う。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| GenericError | ShellError | サポートされていないファイル形式 | 対応形式を使用 |
| GenericError | ShellError | スキーマ不一致 | スキーマを修正 |
| LabeledError | LabeledError | カラム名が存在しない | 正しいカラム名を指定 |
| Panic | GenericError | Polarsパニック発生 | データを確認 |

### リトライ仕様

特になし。エラー発生時は処理を中断する。

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

インメモリ処理のため、トランザクション管理は不要。ファイル保存時は一括書き込み。

## パフォーマンス要件

- 大規模データ処理: 列指向フォーマットによる高速処理
- 遅延評価: 不要な計算をスキップ
- 並列処理: Polarsの内部並列化を活用
- メモリ効率: Arrow形式による効率的なメモリ利用

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

- ファイルアクセスは通常のファイルシステム権限に従う
- クラウドストレージアクセス時は認証情報が必要

## 備考

- Tokioランタイムを内部で使用
- プラグインGCを無効化することで長時間処理が可能
- custom_value_operationにより演算子オーバーロードをサポート

---

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

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

### 推奨読解順序

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

Polarsプラグインの中核となるカスタム値型を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mod.rs | `crates/nu_plugin_polars/src/dataframe/values/mod.rs` | カスタム値型の一覧とCustomValueType enum |
| 1-2 | nu_dataframe/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/nu_dataframe/mod.rs` | NuDataFrameの構造と基本操作 |
| 1-3 | nu_lazyframe/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/nu_lazyframe/mod.rs` | NuLazyFrameの構造と遅延評価 |
| 1-4 | nu_expression/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/nu_expression/mod.rs` | NuExpressionの構造と式表現 |

**読解のコツ**: 各カスタム値はPolarsの対応する型をラップしている。custom_value.rsでCustomValueトレイトの実装を確認すると、シリアライズ/デシリアライズの仕組みがわかる。

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

プラグインのメインエントリーポイントとコマンド登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | lib.rs | `crates/nu_plugin_polars/src/lib.rs` | PolarsPluginの定義とコマンド登録 |
| 2-2 | cache/mod.rs | `crates/nu_plugin_polars/src/cache/mod.rs` | Cacheの定義とカスタム値管理 |

**主要処理フロー（lib.rs）**:
1. **61-66行目**: PolarsPluginの構造体定義（cache, runtime）
2. **68-82行目**: new()でTokioランタイムを初期化
3. **84-106行目**: commands()で全コマンドを登録
4. **108-119行目**: custom_value_dropped()でキャッシュクリーンアップ
5. **121-137行目**: custom_value_to_base_value()でNu値への変換
6. **139-173行目**: custom_value_operation()で演算子処理

#### Step 3: コアコマンドを理解する

主要なデータ操作コマンドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | open.rs | `crates/nu_plugin_polars/src/dataframe/command/core/open.rs` | ファイル読み込み処理 |
| 3-2 | to_df.rs | `crates/nu_plugin_polars/src/dataframe/command/core/to_df.rs` | データフレーム変換 |
| 3-3 | to_lazy.rs | `crates/nu_plugin_polars/src/dataframe/command/core/to_lazy.rs` | 遅延評価への変換 |

#### Step 4: 集計コマンドを理解する

集計処理の実装パターンを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | groupby.rs | `crates/nu_plugin_polars/src/dataframe/command/aggregation/groupby.rs` | グループ化処理 |
| 4-2 | aggregate.rs | `crates/nu_plugin_polars/src/dataframe/command/aggregation/aggregate.rs` | 集計処理 |

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

```
PolarsPlugin::commands()
    │
    ├─ core_commands()
    │      ├─ PolarsOpen
    │      ├─ ToDataFrame
    │      ├─ ToLazy
    │      ├─ Collect
    │      └─ Save
    │
    ├─ aggregation_commands()
    │      ├─ GroupBy
    │      ├─ Aggregate
    │      ├─ Sum / Mean / Min / Max
    │      └─ ...
    │
    ├─ data_commands()
    │      ├─ Select
    │      ├─ Filter
    │      ├─ Join
    │      └─ ...
    │
    └─ string_commands() / datetime_commands() / ...
```

### データフロー図

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

ファイル                  PolarsOpen
(CSV/Parquet) ─────▶     ├─ read_csv()        ─────▶   NuDataFrame
                          └─ read_parquet()              (CustomValue)
                                 │
                                 ▼
                          ToLazy
                                 │
                                 ▼
NuLazyFrame  ─────────▶  Select / Filter      ─────▶   NuLazyFrame
                          GroupBy / Agg                  (計算グラフ)
                                 │
                                 ▼
                          Collect
                                 │
                                 ▼
                          最適化実行           ─────▶   NuDataFrame
                                 │
                                 ▼
                          ToNu                 ─────▶   Nushell Table
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lib.rs | `crates/nu_plugin_polars/src/lib.rs` | ソース | プラグインエントリーポイント |
| cache/mod.rs | `crates/nu_plugin_polars/src/cache/mod.rs` | ソース | カスタム値キャッシュ管理 |
| dataframe/mod.rs | `crates/nu_plugin_polars/src/dataframe/mod.rs` | ソース | データフレームモジュール |
| values/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/mod.rs` | ソース | カスタム値型定義 |
| nu_dataframe/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/nu_dataframe/mod.rs` | ソース | NuDataFrame実装 |
| nu_lazyframe/mod.rs | `crates/nu_plugin_polars/src/dataframe/values/nu_lazyframe/mod.rs` | ソース | NuLazyFrame実装 |
| command/core/open.rs | `crates/nu_plugin_polars/src/dataframe/command/core/open.rs` | ソース | ファイル読み込みコマンド |
| command/aggregation/groupby.rs | `crates/nu_plugin_polars/src/dataframe/command/aggregation/groupby.rs` | ソース | グループ化コマンド |
| command/data/* | `crates/nu_plugin_polars/src/dataframe/command/data/` | ソース | データ操作コマンド群 |
