chdb-datastore

chdb DataStore — pandasをさらに高速に

重要なポイント

# Change this:
import pandas as pd
# To this:
import chdb.datastore as pd
# Everything else stays the same.

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

pip install chdb

選択ガイド：適切な方法を選ぶ

1. "I have a file/database and want to analyze it with pandas"
   → DataStore.from_file() / from_mysql() / from_s3() etc.
   → See references/connectors.md

2. "I need to join data from different sources"
   → Create DataStores from each source, use .join()
   → See examples/examples.md #3-5

3. "My pandas code is too slow"
   → import chdb.datastore as pd — change one line, keep the rest

4. "I need raw SQL queries"
   → Use the chdb-sql skill instead

あらゆるデータソースに接続する — 共通のパターン

from datastore import DataStore

# Local file (auto-detects .parquet, .csv, .json, .arrow, .orc, .avro, .tsv, .xml)
ds = DataStore.from_file("sales.parquet")

# Database
ds = DataStore.from_mysql(host="db:3306", database="shop", table="orders", user="root", password="pass")

# Cloud storage
ds = DataStore.from_s3("s3://bucket/data.parquet", nosign=True)

# URI shorthand — auto-detects source type
ds = DataStore.uri("mysql://root:pass@db:3306/shop/orders")

16種類以上のすべてのデータソースとURIスキーム → connectors.md

接続後 — pandas API全体を利用

result = ds[ds["age"] > 25]                                          # filter
result = ds[["name", "city"]]                                        # select columns
result = ds.sort_values("revenue", ascending=False)                  # sort
result = ds.groupby("dept")["salary"].mean()                         # groupby
result = ds.assign(margin=lambda x: x["profit"] / x["revenue"])     # computed column
ds["name"].str.upper()                                               # string accessor
ds["date"].dt.year                                                   # datetime accessor
result = ds1.join(ds2, on="id")                                      # join
result = ds.head(10)                                                 # preview
print(ds.to_sql())                                                   # see generated 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"ではなく）
結合結果が空になる	キーの型が一致しているか確認します（両方とも整数、または両方とも文字列）。.to_sql() を使って確認します
想定外の結果になる	ds.to_sql() を呼び出して、生成されたSQLを確認し、デバッグします
環境の確認	python scripts/verify_install.py を実行します（スキルのディレクトリから）

参考資料

• APIリファレンス — DataStoreメソッドのシグネチャ一覧
• コネクター — 16種類以上のすべてのデータソース接続メソッド
• 例 — 実行可能な例10件以上と想定される出力
• インストールの確認 — 環境確認スクリプト
• 公式ドキュメント

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