chdb DataStore — より速い Pandas です

キーコンセプト

# これを:
import pandas as pd
# こう変更:
import chdb.datastore as pd
# それ以外は全く同じです。

DataStore は 遅延評価される ClickHouse バックエンドの pandas 互換ライブラリ です。既存の pandas コードはそのまま動作しますが、操作は最適化された SQL にコンパイルされ、結果が必要になったとき (例: print()、len()、反復処理) に実行されます。

pip install chdb

デシジョンツリー: 適切なアプローチを選択

1. 「ファイル/データベースを持っていて、pandas で分析したい」
   → DataStore.from_file() / from_mysql() / from_s3() など
   → references/connectors.md を参照

2. 「異なるソースのデータを結合する必要がある」
   → 各ソースから DataStore を作成し、.join() を使用
   → examples/examples.md #3-5 を参照

3. 「pandas コードが遅すぎる」
   → import chdb.datastore as pd — 1 行変更して、あとはそのまま

4. 「生の SQL クエリが必要」
   → chdb-sql スキルを使用してください

あらゆるデータソースに接続 — 統一されたパターン

from datastore import DataStore

# ローカルファイル (自動検出: .parquet, .csv, .json, .arrow, .orc, .avro, .tsv, .xml)
ds = DataStore.from_file("sales.parquet")

# データベース
ds = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")

# クラウドストレージ
ds = DataStore.from_s3("s3://bucket/data.parquet", nosign=True)

# URI ショートハンド — ソースタイプを自動検出
ds = DataStore.uri("mysql://root:pass@db:3306/shop/orders")

16+ 以上のソースと URI スキーム → connectors.md

接続後 — 完全な Pandas API

result = ds[ds["age"] > 25]                                          # フィルタリング
result = ds[["name", "city"]]                                        # 列を選択
result = ds.sort_values("revenue", ascending=False)                  # ソート
result = ds.groupby("dept")["salary"].mean()                         # グループ化
result = ds.assign(margin=lambda x: x["profit"] / x["revenue"])     # 計算済み列
ds["name"].str.upper()                                               # 文字列アクセッサー
ds["date"].dt.year                                                   # 日時アクセッサー
result = ds1.join(ds2, on="id")                                      # 結合
result = ds.head(10)                                                 # プレビュー
print(ds.to_sql())                                                   # 生成された SQL を確認

209 の DataFrame メソッドをサポート。完全な API → api-reference.md

クロスソース結合 — キラー機能

from datastore import DataStore

customers = DataStore.from_mysql(host="db:3306", database="crm", table="customers", user="root", password="pass")
orders = DataStore.from_file("orders.parquet")

result = (orders
    .join(customers, left_on="customer_id", right_on="id")
    .groupby("country")
    .agg({"amount": "sum", "rating": "mean"})
    .sort_values("sum", ascending=False))
print(result)

結合の例をもっと見る → examples.md

データの書き込み

source = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")
target = DataStore("file", path="summary.parquet", format="Parquet")

target.insert_into("category", "total", "count").select_from(
    source.groupby("category").select("category", "sum(amount) AS total", "count() AS count")
).execute()

トラブルシューティング

問題	解決策
ImportError: No module named 'chdb'	pip install chdb
ImportError: cannot import 'DataStore'	from datastore import DataStore または from chdb.datastore import DataStore を使用
データベース接続がタイムアウト	ホストにポートを含める: host="db:3306" (host="db" ではなく)
結合が空の結果を返す	キーの型が一致しているか確認 (どちらも int または両方 string); .to_sql() を使用して検証
予期しない結果	ds.to_sql() を呼び出して生成された SQL を確認し、デバッグします
環境チェック	python scripts/verify_install.py を実行 (スキルディレクトリから)

参考資料

• API リファレンス — DataStore メソッドの完全なシグネチャー
• コネクター — すべての 16+ データソース接続方法
• 例 — 実行可能な 10+ の例と期待される出力
• インストール検証 — 環境検証スクリプト
• 公式ドキュメント

注: このスキルは chdb DataStore の 使用方法 を教えます。 生の SQL クエリについては、chdb-sql スキルを使用してください。 chdb ソースコードへの貢献については、プロジェクトルートの CLAUDE.md を参照してください。