chdb SQL — ClickHouse dans votre processus Python

Exécutez des requêtes SQL ClickHouse directement en Python — aucun serveur requis. Interrogez des fichiers locaux, des bases de données distantes et du stockage cloud avec toute la puissance SQL de ClickHouse.

pip install chdb

Arbre de décision : Choisissez la bonne API

1. Requête ponctuelle sur fichiers ou BD → chdb.query()
2. Analyse multi-étapes avec tables      → Session
3. Connexion DB-API 2.0                  → chdb.connect()
4. Opérations DataFrame style Pandas     → Utilisez plutôt la skill chdb-datastore

chdb.query() — Une ligne, n'importe quelles données

import chdb

chdb.query("SELECT * FROM file('data.parquet', Parquet) WHERE price > 100 LIMIT 10")       # fichiers locaux
chdb.query("SELECT * FROM mysql('db:3306', 'shop', 'orders', 'root', 'pass')")              # bases de données
chdb.query("SELECT * FROM s3('s3://bucket/data.parquet', NOSIGN) LIMIT 10")                 # stockage cloud
chdb.query("SELECT * FROM deltaLake('s3://bucket/delta/table', NOSIGN) LIMIT 10")           # data lakes

# Jointure multi-sources
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")                                # données Python
df = chdb.query("SELECT * FROM numbers(10)", "DataFrame")                                   # formats de sortie
chdb.query("SELECT toDate({d:String}) + number FROM numbers({n:UInt64})",
    "DataFrame", params={"d": "2025-01-01", "n": 30})                                      # paramétrées

Fonctions table → table-functions.md | Fonctions SQL → sql-functions.md | API complète → api-reference.md

Session — Pipelines d'analyse avec état

from chdb import session as chs
sess = chs.Session("./analytics_db")   # persistante ; Session() pour en mémoire

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()

API de connexion (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()

Dépannage

Problème	Solution
`ImportError: No module named 'chdb'`	`pip install chdb`
`DB::Exception: FILE_NOT_FOUND`	Vérifiez le chemin du fichier ; utilisez un chemin absolu ou vérifiez le répertoire courant
`DB::Exception: Unknown table function`	Vérifiez l'orthographe du nom de fonction (ex. `deltaLake` et non `deltalake`)
Connexion refusée vers BD distante	Vérifiez le format host:port ; assurez-vous que la BD distante accepte les connexions
Vérification d'environnement	Exécutez `python scripts/verify_install.py` (depuis le répertoire de la skill)

Références

Référence API — signatures query/Session/connect
Fonctions table — Toutes les fonctions table ClickHouse
Fonctions SQL — Fonctions SQL couramment utilisées
Exemples — 9 exemples exécutables avec sortie attendue
Documentation officielle

Note : Cette skill enseigne comment utiliser chdb SQL. Pour les opérations style pandas, utilisez la skill chdb-datastore. Pour contribuer au code source de chdb, consultez CLAUDE.md à la racine du projet.

chdb-sql