> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# pandasとの主な違い

> DataStoreとpandasの重要な違い

DataStore は pandas と高い互換性がありますが、理解しておくべき重要な違いがいくつかあります。

<div id="summary">
  ## 概要表
</div>

| 観点          | pandas           | DataStore                                                                |
| ----------- | ---------------- | ------------------------------------------------------------------------ |
| **実行**      | 即時実行             | 遅延実行                                                                     |
| **戻り値の型**   | DataFrame/Series | DataStore/ColumnExpr                                                     |
| **行の順序**    | 保持される            | 自動的に保持される。[パフォーマンスモード](/docs/ja/chdb/configuration/performance-mode) では保証されない |
| **inplace** | 対応               | 非対応                                                                      |
| **索引**      | 完全対応             | 簡略化                                                                      |
| **メモリ**     | すべてのデータをメモリ上に保持  | データは元の場所に保持                                                              |

***

<div id="lazy-execution">
  ## 1. 遅延実行と即時実行
</div>

<div id="pandas-eager">
  ### pandas (即時実行)
</div>

操作は即座に実行されます。

```python theme={null}
import pandas as pd

df = pd.read_csv("data.csv")  # Loads entire file NOW
result = df[df['age'] > 25]   # Filters NOW
grouped = result.groupby('city')['salary'].mean()  # Aggregates NOW
```

<div id="datastore-lazy">
  ### DataStore (遅延実行)
</div>

結果が必要になるまで、操作は実行されません。

```python theme={null}
from chdb import datastore as pd

ds = pd.read_csv("data.csv")  # Just records the source
result = ds[ds['age'] > 25]   # Just records the filter
grouped = result.groupby('city')['salary'].mean()  # Just records

# Execution happens here:
print(grouped)        # Executes when displaying
df = grouped.to_df()  # Or when converting to pandas
```

<div id="why-lazy">
  ### なぜ重要か
</div>

遅延実行には、次の利点があります。

* **クエリ最適化**: 複数の操作が 1 つの SQL クエリにコンパイルされる
* **カラムプルーニング**: 必要なカラムだけが読み込まれる
* **フィルタのプッシュダウン**: フィルタがデータソース側で適用される
* **メモリ効率**: 必要のないデータは読み込まない

***

<div id="return-types">
  ## 2. 戻り値の型
</div>

<div id="pandas-return-types">
  ### pandas
</div>

```python theme={null}
df['col']           # Returns pd.Series
df[['a', 'b']]      # Returns pd.DataFrame
df[df['x'] > 10]    # Returns pd.DataFrame
df.groupby('x')     # Returns DataFrameGroupBy
```

<div id="datastore-return-types">
  ### DataStore
</div>

```python theme={null}
ds['col']           # Returns ColumnExpr (lazy)
ds[['a', 'b']]      # Returns DataStore (lazy)
ds[ds['x'] > 10]    # Returns DataStore (lazy)
ds.groupby('x')     # Returns LazyGroupBy
```

<div id="converting-to-pandas-types">
  ### pandasの型への変換
</div>

```python theme={null}
# Get pandas DataFrame
df = ds.to_df()
df = ds.to_pandas()

# Get pandas Series from column
series = ds['col'].to_pandas()

# Or trigger execution
print(ds)  # Automatically converts for display
```

***

<div id="triggers">
  ## 3. 実行トリガー
</div>

DataStore は、実際の値が必要になった時点で実行されます。

| トリガー                 | 例                  | 注記         |
| -------------------- | ------------------ | ---------- |
| `print()` / `repr()` | `print(ds)`        | 表示にはデータが必要 |
| `len()`              | `len(ds)`          | 行数が必要      |
| `.columns`           | `ds.columns`       | カラム名が必要    |
| `.dtypes`            | `ds.dtypes`        | 型情報が必要     |
| `.shape`             | `ds.shape`         | 次元数が必要     |
| `.values`            | `ds.values`        | 実データが必要    |
| `.index`             | `ds.index`         | インデックスが必要  |
| `to_df()`            | `ds.to_df()`       | 明示的な変換     |
| Iteration            | `for row in ds`    | 反復処理が必要    |
| `equals()`           | `ds.equals(other)` | 比較が必要      |

<div id="stay-lazy">
  ### 遅延実行のままになる操作
</div>

| 操作               | 戻り値         |
| ---------------- | ----------- |
| `filter()`       | DataStore   |
| `select()`       | DataStore   |
| `sort()`         | DataStore   |
| `groupby()`      | LazyGroupBy |
| `join()`         | DataStore   |
| `ds['col']`      | ColumnExpr  |
| `ds[['a', 'b']]` | DataStore   |
| `ds[condition]`  | DataStore   |

***

<div id="row-order">
  ## 4. 行の並び順
</div>

<div id="pandas-return-types">
  ### pandas
</div>

行の順序は常に維持されます。

```python theme={null}
df = pd.read_csv("data.csv")
print(df.head())  # Always same order as file
```

<div id="datastore-return-types">
  ### DataStore
</div>

多くの操作では、行の順序は**自動的に保持されます**：

```python theme={null}
ds = pd.read_csv("data.csv")
print(ds.head())  # Matches file order

# Filter preserves order
ds_filtered = ds[ds['age'] > 25]  # Same order as pandas
```

DataStore は、pandas と同じ順序を保てるように、元の行位置を内部で自動的に追跡します (`rowNumberInAllBlocks()` を使用) 。

<div id="order-preserved">
  ### 順序が保持される場合
</div>

* ファイルソース (CSV、Parquet、JSON など)
* pandas DataFrame ソース
* フィルタ操作
* カラムの選択
* `sort()` または `sort_values()` を明示的に実行した後
* 順序を定義する操作 (`nlargest()`, `nsmallest()`, `head()`, `tail()`)

<div id="order-may-differ">
  ### 順序が変わることがある場合
</div>

* `groupby()` による集計の後 (順序を一定にしたい場合は `sort_values()` を使用してください)
* 特定の JOIN 種別で `merge()` / `join()` を行った後
* **パフォーマンスモード** (`config.use_performance_mode()`) では、どの操作でも行の順序は保証されません。詳細は [パフォーマンスモード](/docs/ja/chdb/configuration/performance-mode) を参照してください。

***

<div id="no-inplace">
  ## 5. inplace パラメータなし
</div>

<div id="pandas-return-types">
  ### pandas
</div>

```python theme={null}
df.drop(columns=['col'], inplace=True)  # Modifies df
df.fillna(0, inplace=True)              # Modifies df
df.rename(columns={'old': 'new'}, inplace=True)
```

<div id="datastore-return-types">
  ### DataStore
</div>

`inplace=True` はサポートされていません。必ず結果を代入してください。

```python theme={null}
ds = ds.drop(columns=['col'])           # Returns new DataStore
ds = ds.fillna(0)                       # Returns new DataStore
ds = ds.rename(columns={'old': 'new'})  # Returns new DataStore
```

<div id="why-no-inplace">
  ### なぜ inplace はないのでしょうか？
</div>

DataStore は、以下を実現するためにイミュータブルな操作を採用しています。

* クエリの構築 (遅延評価)
* スレッドセーフ
* デバッグのしやすさ
* よりクリーンなコード

***

<div id="index">
  ## 6. 索引のサポート
</div>

<div id="pandas-return-types">
  ### pandas
</div>

索引を完全にサポート：

```python theme={null}
df = df.set_index('id')
df.loc['user123']           # Label-based access
df.loc['a':'z']             # Label-based slicing
df.reset_index()
df.index.name = 'user_id'
```

<div id="datastore-return-types">
  ### DataStore
</div>

簡易的な索引サポート:

```python theme={null}
# Basic operations work
ds.loc[0:10]               # Integer position
ds.iloc[0:10]              # Same as loc for DataStore

# For pandas-style index operations, convert first
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']
```

<div id="datastore-source-matters">
  ### DataStore ではソースの違いが重要です
</div>

* **DataFrame ソース**: pandas のインデックスを保持します
* **File ソース**: シンプルな整数インデックスを使用します

***

<div id="comparison">
  ## 7. 比較時の動作
</div>

<div id="comparing-with-pandas">
  ### pandas との比較
</div>

pandas は DataStore オブジェクトを認識できません:

```python theme={null}
import pandas as pd
from chdb import datastore as ds

pdf = pd.DataFrame({'a': [1, 2, 3]})
dsf = ds.DataFrame({'a': [1, 2, 3]})

# This doesn't work as expected
pdf == dsf  # pandas doesn't know DataStore

# Solution: convert DataStore to pandas
pdf.equals(dsf.to_pandas())  # True
```

<div id="using-equals">
  ### equals() を使用する
</div>

```python theme={null}
# DataStore.equals() also works
dsf.equals(pdf)  # Compares with pandas DataFrame
```

***

<div id="types">
  ## 8. 型推論
</div>

<div id="pandas-return-types">
  ### pandas
</div>

numpy/pandas のデータ型を使用します:

```python theme={null}
df['col'].dtype  # int64, float64, object, datetime64, etc.
```

<div id="datastore-return-types">
  ### DataStore
</div>

ClickHouseの型を使用できます。

```python theme={null}
ds['col'].dtype  # Int64, Float64, String, DateTime, etc.

# Types are converted when going to pandas
df = ds.to_df()
df['col'].dtype  # Now pandas type
```

<div id="explicit-casting">
  ### 明示的なキャスト
</div>

```python theme={null}
# Force specific type
ds['col'] = ds['col'].astype('int64')
```

***

<div id="memory">
  ## 9. メモリモデル
</div>

<div id="pandas-return-types">
  ### pandas
</div>

すべてのデータはメモリ上に保持されます。

```python theme={null}
df = pd.read_csv("huge.csv")  # 10GB in memory!
```

<div id="datastore-return-types">
  ### DataStore
</div>

データは必要になるまでソース側に保持されます:

```python theme={null}
ds = pd.read_csv("huge.csv")  # Just metadata
ds = ds.filter(ds['year'] == 2024)  # Still just metadata

# Only filtered result is loaded
df = ds.to_df()  # Maybe only 1GB now
```

***

<div id="errors">
  ## 10. エラーメッセージ
</div>

<div id="different-error-sources">
  ### エラーの発生元の違い
</div>

* **pandas errors**: pandasライブラリに由来
* **DataStore errors**: chDB または ClickHouse に由来

```python theme={null}
# May see ClickHouse-style errors
# "Code: 62. DB::Exception: Syntax error..."
```

<div id="debugging-tips">
  ### デバッグのヒント
</div>

```python theme={null}
# View the SQL to debug
print(ds.to_sql())

# See execution plan
ds.explain()

# Enable debug logging
from chdb.datastore.config import config
config.enable_debug()
```

***

<div id="checklist">
  ## 移行チェックリスト
</div>

pandas から移行する場合:

* [ ] import 文を変更する
* [ ] `inplace=True` パラメータを削除する
* [ ] pandas DataFrame が必要な箇所では、明示的に `to_df()` を追加する
* [ ] 行の順序が重要な場合はソートを追加する
* [ ] 比較テストには `to_pandas()` を使用する
* [ ] 実際の使用を想定したデータサイズでテストする

***

<div id="quick-ref">
  ## クイックリファレンス
</div>

| pandas                  | DataStore                      |
| ----------------------- | ------------------------------ |
| `df[condition]`         | 同じ (DataStore が返されます)          |
| `df.groupby()`          | 同じ (LazyGroupBy が返されます)        |
| `df.drop(inplace=True)` | `ds = ds.drop()`               |
| `df.equals(other)`      | `ds.to_pandas().equals(other)` |
| `df.loc['label']`       | `ds.to_df().loc['label']`      |
| `print(df)`             | 同じ (実行がトリガーされます)               |
| `len(df)`               | 同じ (実行がトリガーされます)               |