pandas との主な違い

DataStore と pandas の主な違い

DataStore は pandas と高い互換性がありますが、押さえておくべき重要な違いもあります。

​

サマリー表

項目	pandas	DataStore
実行	即時実行 (即時)	遅延実行 (遅延)
戻り値の型	DataFrame/Series	DataStore/ColumnExpr
行順	維持される	維持される (自動) 。ただし、performance mode では保証されない
inplace	サポートされる	サポートされない
索引	完全対応	簡易的
メモリ	すべてのデータがメモリ上にある	データはソース側に保持される

---

​

1. 遅延実行と即時実行

​

pandas (即時実行)

操作はすぐに実行されます。

import pandas as pd

df = pd.read_csv("data.csv")  # ファイル全体を即座に読み込む
result = df[df['age'] > 25]   # 即座にフィルタリングする
grouped = result.groupby('city')['salary'].mean()  # 即座に集計する

​

DataStore (遅延実行)

結果が必要になるまで、処理は実行されません：

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

df['col']           # pd.Series を返す
df[['a', 'b']]      # pd.DataFrame を返す
df[df['x'] > 10]    # pd.DataFrame を返す
df.groupby('x')     # DataFrameGroupBy を返す

​

DataStore

ds['col']           # ColumnExpr を返す（遅延実行）
ds[['a', 'b']]      # DataStore を返す（遅延実行）
ds[ds['x'] > 10]    # DataStore を返す（遅延実行）
ds.groupby('x')     # LazyGroupBy を返す

​

pandasのデータ型への変換

# 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

行の順序は常に保たれます：

df = pd.read_csv("data.csv")
print(df.head())  # 常にファイルと同じ順序

​

DataStore

ほとんどの操作では、行の順序は自動的に保持されます。

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 を参照してください。

---

​

5. inplace パラメーターはありません

​

pandas

df.drop(columns=['col'], inplace=True)  # dfを変更する
df.fillna(0, inplace=True)              # dfを変更する
df.rename(columns={'old': 'new'}, inplace=True)

​

DataStore

inplace=True には対応していません。必ず結果を代入してください。

ds = ds.drop(columns=['col'])           # 新しい DataStore を返す
ds = ds.fillna(0)                       # 新しい DataStore を返す
ds = ds.rename(columns={'old': 'new'})  # 新しい DataStore を返す

​

なぜ inplace はないのか？

DataStore では、次のことを可能にするためにイミュータブルな操作を採用しています。

• クエリの構築 (遅延評価)
• スレッドセーフ
• デバッグの容易化
• よりクリーンなコード

---

​

6. 索引のサポート

​

pandas

索引を完全にサポート:

df = df.set_index('id')
df.loc['user123']           # ラベルベースのアクセス
df.loc['a':'z']             # ラベルベースのスライス
df.reset_index()
df.index.name = 'user_id'

​

DataStore

簡易な索引サポート:

# 基本的な操作
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 オブジェクトを認識できません：

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() の使用

# DataStore.equals() も使用可能
dsf.equals(pdf)  # pandas DataFrame と比較

---

​

8. 型推論

​

pandas

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

df['col'].dtype  # int64、float64、object、datetime64 など

​

DataStore

ClickHouse の型を使用できます:

ds['col'].dtype  # Int64, Float64, String, DateTime, etc.

# pandasに変換する際に型が変換される
df = ds.to_df()
df['col'].dtype  # Now pandas type

​

明示的な型変換

# 特定の型に強制変換する
ds['col'] = ds['col'].astype('int64')

---

​

9. メモリモデル

​

pandas

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

df = pd.read_csv("huge.csv")  # メモリに10GB！

​

DataStore

データは必要になるまで、元のソースに保持されます。

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 に起因

# ClickHouse形式のエラーが表示されることがあります
# "Code: 62. DB::Exception: Syntax error..."

​

デバッグのヒント

# デバッグ用に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)	同じ (実行がトリガーされる)