> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# pandas との主な違い
> DataStore と pandas の主な違い
DataStore は pandas と高い互換性がありますが、押さえておくべき重要な違いもあります。
## サマリー表
| 項目 | pandas | DataStore |
| ----------- | ---------------- | --------------------------------------------------------------------------------------------- |
| **実行** | 即時実行 (即時) | 遅延実行 (遅延) |
| **戻り値の型** | DataFrame/Series | DataStore/ColumnExpr |
| **行順** | 維持される | 維持される (自動) 。ただし、[performance mode](/ja/products/chdb/configuration/performance-mode) では保証されない |
| **inplace** | サポートされる | サポートされない |
| **索引** | 完全対応 | 簡易的 |
| **メモリ** | すべてのデータがメモリ上にある | データはソース側に保持される |
***
## 1. 遅延実行と即時実行
### pandas (即時実行)
操作はすぐに実行されます。
```python theme={null}
import pandas as pd
df = pd.read_csv("data.csv") # ファイル全体を即座に読み込む
result = df[df['age'] > 25] # 即座にフィルタリングする
grouped = result.groupby('city')['salary'].mean() # 即座に集計する
```
### DataStore (遅延実行)
結果が必要になるまで、処理は実行されません：
```python theme={null}
from chdb import datastore as pd
ds = pd.read_csv("data.csv") # ソースを記録するだけ
result = ds[ds['age'] > 25] # フィルターを記録するだけ
grouped = result.groupby('city')['salary'].mean() # 記録するだけ
# ここで実行される:
print(grouped) # 表示時に実行
df = grouped.to_df() # またはpandasへの変換時に実行
```
### これが重要な理由
遅延実行には、次の利点があります。
* **クエリ最適化**: 複数の操作が1つのSQLクエリにまとめられます
* **カラムの絞り込み**: 必要なカラムだけが読み込まれます
* **フィルタのプッシュダウン**: フィルタがソース側で適用されます
* **メモリ効率**: 必要のないデータは読み込みません
***
## 2. 戻り値の型
### pandas
```python theme={null}
df['col'] # pd.Series を返す
df[['a', 'b']] # pd.DataFrame を返す
df[df['x'] > 10] # pd.DataFrame を返す
df.groupby('x') # DataFrameGroupBy を返す
```
### DataStore
```python theme={null}
ds['col'] # ColumnExpr を返す（遅延実行）
ds[['a', 'b']] # DataStore を返す（遅延実行）
ds[ds['x'] > 10] # DataStore を返す（遅延実行）
ds.groupby('x') # LazyGroupBy を返す
```
### pandasのデータ型への変換
```python theme={null}
# pandas DataFrameを取得
df = ds.to_df()
df = ds.to_pandas()
# カラムからpandas Seriesを取得
series = ds['col'].to_pandas()
# または実行をトリガー
print(ds) # 表示用に自動変換
```
***
## 3. 実行トリガー
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()` | 明示的な変換 |
| 反復処理 | `for row in ds` | 反復処理が必要 |
| `equals()` | `ds.equals(other)` | 比較が必要 |
### 遅延実行のままの操作
| 操作 | 戻り値 |
| ---------------- | ----------- |
| `filter()` | DataStore |
| `select()` | DataStore |
| `sort()` | DataStore |
| `groupby()` | LazyGroupBy |
| `join()` | DataStore |
| `ds['col']` | ColumnExpr |
| `ds[['a', 'b']]` | DataStore |
| `ds[condition]` | DataStore |
***
## 4. 行の並び順
### pandas
行の順序は常に保たれます：
```python theme={null}
df = pd.read_csv("data.csv")
print(df.head()) # 常にファイルと同じ順序
```
### DataStore
ほとんどの操作では、行の順序は**自動的に保持**されます。
```python theme={null}
ds = pd.read_csv("data.csv")
print(ds.head()) # ファイルの順序と一致
# フィルター適用後も順序は保持される
ds_filtered = ds[ds['age'] > 25] # pandasと同じ順序
```
DataStore は、pandas と同じ順序の整合性を保つため、元の行位置を内部で (`rowNumberInAllBlocks()` を使って) 自動的に追跡します。
### 順序が保持されるケース
* ファイルソース (CSV、Parquet、JSON など)
* pandas DataFrame ソース
* フィルタ処理
* カラムの選択
* 明示的に `sort()` または `sort_values()` を実行した後
* 順序を決定する操作 (`nlargest()`、`nsmallest()`、`head()`、`tail()`)
### 順序が変わる可能性がある場合
* `groupby()` による集計の後 (順序を一定に保つには `sort_values()` を使用してください)
* 特定の join 型で `merge()` / `join()` を実行した後
* **performance mode** (`config.use_performance_mode()`) では、どの操作でも行の順序は保証されません。詳しくは [Performance Mode](/ja/products/chdb/configuration/performance-mode) を参照してください。
***
## 5. inplace パラメーターはありません
### pandas
```python theme={null}
df.drop(columns=['col'], inplace=True) # dfを変更する
df.fillna(0, inplace=True) # dfを変更する
df.rename(columns={'old': 'new'}, inplace=True)
```
### DataStore
`inplace=True` には対応していません。必ず結果を代入してください。
```python theme={null}
ds = ds.drop(columns=['col']) # 新しい DataStore を返す
ds = ds.fillna(0) # 新しい DataStore を返す
ds = ds.rename(columns={'old': 'new'}) # 新しい DataStore を返す
```
### なぜ inplace はないのか？
DataStore では、次のことを可能にするためにイミュータブルな操作を採用しています。
* クエリの構築 (遅延評価)
* スレッドセーフ
* デバッグの容易化
* よりクリーンなコード
***
## 6. 索引のサポート
### pandas
索引を完全にサポート:
```python theme={null}
df = df.set_index('id')
df.loc['user123'] # ラベルベースのアクセス
df.loc['a':'z'] # ラベルベースのスライス
df.reset_index()
df.index.name = 'user_id'
```
### DataStore
簡易な索引サポート:
```python theme={null}
# 基本的な操作
ds.loc[0:10] # 整数位置
ds.iloc[0:10] # DataStore では loc と同じ
# pandas スタイルの索引操作を行う場合は、先に変換する
df = ds.to_df()
df = df.set_index('id')
df.loc['user123']
```
### DataStore ではソースの種類が重要です
* **DataFrame ソース**: pandas の索引を保持します
* **File ソース**: シンプルな整数索引を使用します
***
## 7. 比較時の挙動
### pandas との比較
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]})
# これは期待通りに動作しない
pdf == dsf # pandasはDataStoreを認識しない
# 解決策: DataStoreをpandasに変換する
pdf.equals(dsf.to_pandas()) # True
```
### equals() の使用
```python theme={null}
# DataStore.equals() も使用可能
dsf.equals(pdf) # pandas DataFrame と比較
```
***
## 8. 型推論
### pandas
numpy/pandas の型を使用します:
```python theme={null}
df['col'].dtype # int64、float64、object、datetime64 など
```
### DataStore
ClickHouse の型を使用できます:
```python theme={null}
ds['col'].dtype # Int64, Float64, String, DateTime, etc.
# pandasに変換する際に型が変換される
df = ds.to_df()
df['col'].dtype # Now pandas type
```
### 明示的な型変換
```python theme={null}
# 特定の型に強制変換する
ds['col'] = ds['col'].astype('int64')
```
***
## 9. メモリモデル
### pandas
すべてのデータはメモリ上に保持されます。
```python theme={null}
df = pd.read_csv("huge.csv") # メモリに10GB！
```
### DataStore
データは必要になるまで、元のソースに保持されます。
```python theme={null}
ds = pd.read_csv("huge.csv") # メタデータのみ
ds = ds.filter(ds['year'] == 2024) # まだメタデータのみ
# フィルタリングされた結果のみが読み込まれる
df = ds.to_df() # おそらく1GB程度
```
***
## 10. エラーメッセージ
### エラーの種類
* **pandas errors**: pandasライブラリに起因
* **DataStore errors**: chDB または ClickHouse に起因
```python theme={null}
# ClickHouse形式のエラーが表示されることがあります
# "Code: 62. DB::Exception: Syntax error..."
```
### デバッグのヒント
```python theme={null}
# デバッグ用にSQLを表示する
print(ds.to_sql())
# 実行計画を確認する
ds.explain()
# デバッグログを有効にする
from chdb.datastore.config import config
config.enable_debug()
```
***
## 移行チェックリスト
pandas から移行する場合:
* [ ] インポート文を変更する
* [ ] `inplace=True` パラメータを削除する
* [ ] pandas DataFrame が必要な箇所では、明示的に `to_df()` を追加する
* [ ] 行の順序が重要な場合はソートを追加する
* [ ] 比較テストには `to_pandas()` を使用する
* [ ] 実際のデータ量を想定したサイズでテストする
***
## クイックリファレンス
| 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)` | 同じ (実行がトリガーされる) |