chdb

What it is and what it does

chDB embeds ClickHouse's SQL OLAP engine directly into Python, letting you run SQL queries on local files and in-memory data without installing a separate database server. It supports multiple input/output formats (Parquet, CSV, JSON, Arrow, ORC, and 60+ others) and offers two APIs: a low-level SQL interface for direct queries, and a pandas-compatible API that compiles operations to optimized SQL.

The package is designed for analytics workflows where you need SQL performance on moderately large datasets without the operational overhead of a database server. It uses lazy evaluation to defer execution until results are needed, and minimizes data transfer between C++ and Python through memory views. Runtime dependencies include chdb-core, pandas, and pyarrow.

Use it for:

• Analyze Parquet or CSV files with SQL queries without loading them entirely into memory.
• Use familiar pandas syntax while getting ClickHouse SQL performance on large datasets.
• Execute SQL queries on multiple file formats and data sources with a unified interface.
• Build interactive data exploration workflows in Jupyter notebooks with lazy evaluation.
• Perform aggregations and groupby operations on large datasets using ClickHouse's multi-threaded engine.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

chDB is an in-process SQL OLAP engine powered by ClickHouse that executes SQL queries on local data without requiring a separate ClickHouse server installation.

Yes. chDB is actively maintained, has no known vulnerabilities, low install friction, and a permissive license. It fills a clear niche for developers who want SQL analytics performance without database infrastructure. The pandas-compatible API lowers the learning curve for existing pandas users, and the SQL API provides escape hatches for advanced ClickHouse features.

Install

chdb on PyPI

pip install chdb

uv add chdb

poetry add chdb

Installing chdb

Before you install

Low friction: pure Python wheel with three runtime dependencies (chdb-core, pandas, pyarrow). Active maintenance with a recent release (32 days old) and 2868 repository stars.

License in practice

Apache-2.0 permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install chdb

import chdb
res = chdb.query('SELECT 1 as num', 'Pretty')
print(res)

# Or with pandas:
import pandas
df = pandas.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 30]})
print(df[df['age'] > 26])

Requires Python 3.9+; supports macOS and Linux (x86_64 and ARM64) only.

Verify before relying

• Whether the pandas-compatible API is fully production-ready or still experimental.
• Performance characteristics and memory overhead when processing datasets larger than available RAM.
• Support status for Windows or other operating systems beyond macOS and Linux.

Package facts

Evidence: chdb-4.2.1-py3-none-any.whl

Keywords: chdb, clickhouse, olap, analytics, database, sql

Tags

More Libraries packages