chdb-sql

chdb SQL — Python プロセス内の ClickHouse

サーバー不要で、Python から ClickHouse SQL を直接実行できます。ClickHouse SQL の機能をフル活用して、ローカルファイル、リモートデータベース、クラウドストレージをクエリできます。

pip install chdb

決定ツリー：適切な API を選ぶ

1. One-off query on files or databases → chdb.query()
2. Multi-step analysis with tables      → Session
3. DB-API 2.0 connection                → chdb.connect()
4. Pandas-style DataFrame operations    → Use chdb-datastore skill instead

chdb.query() — 1 行であらゆるデータを扱う

import chdb

chdb.query("SELECT * FROM file('data.parquet', Parquet) WHERE price > 100 LIMIT 10")       # local files
chdb.query("SELECT * FROM mysql('db:3306', 'shop', 'orders', 'root', 'pass')")              # databases
chdb.query("SELECT * FROM s3('s3://bucket/data.parquet', NOSIGN) LIMIT 10")                 # cloud storage
chdb.query("SELECT * FROM deltaLake('s3://bucket/delta/table', NOSIGN) LIMIT 10")           # data lakes

# Cross-source join
chdb.query("""
    SELECT u.name, o.amount FROM mysql('db:3306', 'crm', 'users', 'root', 'pass') AS u
    JOIN file('orders.parquet', Parquet) AS o ON u.id = o.user_id ORDER BY o.amount DESC
""")

data = {"name": ["Alice", "Bob"], "score": [95, 87]}
chdb.query("SELECT * FROM Python(data) ORDER BY score DESC")                                # Python data
df = chdb.query("SELECT * FROM numbers(10)", "DataFrame")                                   # output formats
chdb.query("SELECT toDate({d:String}) + number FROM numbers({n:UInt64})",
    "DataFrame", params={"d": "2025-01-01", "n": 30})                                      # parametrized

テーブル関数 → table-functions.md | SQL 関数 → sql-functions.md | API 全体 → api-reference.md

Session — 状態を保持する分析パイプライン

from chdb import session as chs
sess = chs.Session("./analytics_db")   # persistent; Session() for in-memory

sess.query("CREATE TABLE users ENGINE=MergeTree() ORDER BY id AS SELECT * FROM mysql('db:3306','crm','users','root','pass')")
sess.query("CREATE TABLE events ENGINE=MergeTree() ORDER BY (ts,user_id) AS SELECT * FROM s3('s3://logs/events/*.parquet',NOSIGN)")
sess.query("""
    SELECT u.country, count() AS cnt, uniqExact(e.user_id) AS users
    FROM events e JOIN users u ON e.user_id = u.id
    WHERE e.ts >= today() - 7 GROUP BY u.country ORDER BY cnt DESC
""", "Pretty").show()
sess.close()

Connection API（DB-API 2.0）

from chdb import dbapi
conn = dbapi.connect()
cur = conn.cursor()
cur.execute("SELECT * FROM file('data.parquet', Parquet) WHERE value > 100")
print(cur.fetchall())
cur.close()
conn.close()

トラブルシューティング

問題	解決方法
ImportError: No module named 'chdb'	pip install chdb
DB::Exception: FILE_NOT_FOUND	ファイルパスを確認してください。絶対パスを使うか、cwd を確認してください
DB::Exception: Unknown table function	関数名のスペルを確認してください（例：deltalake ではなく deltaLake）
リモート DB への接続が拒否される	host:port 形式を確認し、リモート DB が接続を許可していることを確認してください
環境の確認	python scripts/verify_install.py を実行してください（スキルディレクトリから）

参考資料

• API リファレンス — query／Session／connect のシグネチャ
• テーブル関数 — ClickHouse のすべてのテーブル関数
• SQL 関数 — よく使われる SQL 関数
• 例 — 実行可能な例 9 件と期待される出力
• 公式ドキュメント

注：このスキルでは、chdb SQL の 使い方 を説明します。 pandas 形式の操作には、chdb-datastore スキルを使用してください。 chdb のソースコードへの貢献については、プロジェクトルートの CLAUDE.md を参照してください。