chDB

chDB is an in-process SQL OLAP Engine powered by ClickHouse [^1] For more details: The birth of chDB

Features

• 🐼 Pandas-compatible DataStore API - Use familiar pandas syntax with ClickHouse performance
• 🌐 Runs in the browser via WebAssembly - chDB-Wasm compiles the full engine to WASM; try it live at wasm.chdb.io
• In-process SQL OLAP Engine, powered by ClickHouse
• No need to install ClickHouse
• Minimized data copy from C++ to Python with python memoryview
• Input&Output support Parquet, CSV, JSON, Arrow, ORC and 60+more formats
• Support Python DB API 2.0

Get Started on Hex

• 📖 Getting Started Tutorial — set up your first connection
• 🚀 Extended 30-day Hex Trial — full access to ClickHouse integrations

Arch

Installation

Currently, chDB supports Python 3.9+ on macOS and Linux (x86_64 and ARM64).

pip install chdb

No install at all: open wasm.chdb.io and run SQL against the WebAssembly build (chDB-Wasm) right in your browser.

Install ADBC support with Python 3.10 or later:

pip install "chdb[adbc]"

---

🐼 DataStore: Pandas-Compatible API (Recommended)

DataStore provides a familiar pandas-like API with automatic SQL generation and ClickHouse performance. Write pandas code, get SQL performance - no learning curve required.

Quick Start (30 seconds)

Just change your import - use the pandas API you already know:

import datastore as pd  # That's it! Use pandas API as usual

# Create a DataFrame - works exactly like pandas
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie', 'Diana'],
    'age': [25, 30, 35, 28],
    'city': ['NYC', 'LA', 'NYC', 'LA']
})

# Filter with familiar pandas syntax
result = df[df['age'] > 26]
print(result)
#       name  age city
# 1      Bob   30   LA
# 2  Charlie   35  NYC
# 3    Diana   28   LA

# GroupBy works too
print(df.groupby('city')['age'].mean())
# city
# LA     29.0
# NYC    30.0

✨ Zero code changes required. All operations are lazy - they’re recorded and compiled into optimized SQL, executed only when results are needed.

Why DataStore?

Architecture

DataStore uses lazy evaluation with dual-engine execution:

1. Lazy Operation Chain: Operations are recorded, not executed immediately
2. Smart Engine Selection: QueryPlanner routes each segment to optimal engine (chDB for SQL, Pandas for complex ops)
3. Intermediate Caching: Results cached at each step for fast iterative exploration

Working with Files

from datastore import DataStore

# Load any file format
ds = DataStore.from_file("data.parquet")  # or CSV, JSON, ORC...

# Explore your data
print(ds.head())       # Preview first 5 rows
print(ds.shape)        # (rows, columns)
print(ds.columns)      # Column names

# Build queries with method chaining
result = (ds
    .select("product", "revenue", "date")
    .filter(ds.revenue > 1000)
    .sort("revenue", ascending=False)
    .head(10))

print(result)

Query Any Data Source

from datastore import DataStore

# S3 (with anonymous access)
ds = DataStore.uri("s3://bucket/data.parquet?nosign=true")

# MySQL
ds = DataStore.uri("mysql://user:pass@localhost:3306/mydb/users")

# PostgreSQL
ds = DataStore.uri("postgresql://user:pass@localhost:5432/mydb/products")

# And more: SQLite, MongoDB, ClickHouse, HDFS, Azure, GCS...

Pandas API Coverage

DataStore implements comprehensive pandas compatibility:

# All these pandas methods work:
df.drop(columns=['unused'])
df.fillna(0)
df.assign(revenue=lambda x: x['price'] * x['quantity'])
df.sort_values('revenue', ascending=False)
df.groupby('category').agg({'revenue': 'sum', 'quantity': 'mean'})
df.merge(other_df, on='id')
df.pivot_table(values='sales', index='date', columns='product')
# ... and 200+ more

String and DateTime Operations

# String operations via .str accessor
ds['name'].str.upper()
ds['email'].str.contains('@gmail')
ds['text'].str.replace('old', 'new')

# DateTime operations via .dt accessor  
ds['date'].dt.year
ds['date'].dt.month
ds['timestamp'].dt.hour

Documentation

• Pandas Compatibility Guide - Full list of supported methods
• Function Reference - 334 ClickHouse SQL functions
• Migration Guide - Step-by-step guide for pandas users

---

SQL API

For users who prefer SQL or need advanced ClickHouse features:

Run in command line

python3 -m chdb SQL [OutputFormat]

python3 -m chdb "SELECT 1,'abc'" Pretty

Data Input

The following methods are available to access on-disk and in-memory data formats:

For more examples, see examples and tests.

Demos and Examples

• chDB-Wasm browser SQL shell — the full ClickHouse engine in WebAssembly, zero install (source)
• Project Documentation and Usage Examples
• Colab Notebooks and other Script Examples

Benchmark

• ClickBench of embedded engines

• chDB vs Pandas

• Benchmark on DataFrame: chDB Pandas DuckDB Polars

Documentation

• For chdb specific examples and documentation refer to chDB docs
• For SQL syntax, please refer to ClickHouse SQL Reference
• For DataStore API, see Pandas Compatibility Guide

AI Coding Agent Skills

chdb provides two AI Skills that teach AI coding agents (Cursor, Claude Code, Codex, etc.) how to use chdb:

• chdb-datastore — Drop-in pandas replacement. import chdb.datastore as pd, keep existing code unchanged, get ClickHouse performance.
• chdb-sql — In-process ClickHouse SQL. Run chdb.query(), use Session for stateful pipelines, query any file or database with SQL.

Install both so your AI assistant can write correct chdb code out of the box:

curl -sL https://raw.githubusercontent.com/chdb-io/chdb/main/install_skill.sh | bash

For project-level installation (git-committable, shared with your team):

curl -sL https://raw.githubusercontent.com/chdb-io/chdb/main/install_skill.sh | bash -s -- --project

Agent Framework Integrations

chdb.agents ships an agent-safe tool surface (ChDBTool: read-only by default, capped results, errors returned as envelopes the model can self-correct from), and every framework binding below is a thin shell over it — same tool names, descriptions, and behavior everywhere:

• LlamaIndex — pip install llama-index-tools-chdb, then ChDBToolSpec().to_tool_list().
• Pydantic AI — pip install pydantic-ai-chdb, then Agent(..., capabilities=[ChDBCapability()]); typed engine errors become ModelRetry.
• smolagents — built in: from chdb.agents.smolagents import chdb_smol_tools (requires pip install smolagents).
• MCP — mcp-clickhouse runs chdb in-process (CHDB_ENABLED=true) for any MCP-speaking agent.
• Node.js — the chdb npm package ships Vercel AI SDK (chdb/ai-sdk) and Mastra (chdb/mastra) adapters.

Events

• Demo chDB at ClickHouse v23.7 livehouse! and Slides

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

See CONTRIBUTING.md for setup, the modify-then-test workflow, PR & commit conventions, CI, and releases. Things you can help with:

• [ ] Help test and report bugs
• [ ] Help improve documentation
• [ ] Help improve code quality and performance

Bindings

We welcome bindings for other languages, please refer to bindings for more details.

Version Guide

Please refer to VERSION-GUIDE.md for more details.

Paper

• ClickHouse - Lightning Fast Analytics for Everyone

Language Binding Capability Matrix

The table below summarizes the user-facing capabilities of the chdb-io language bindings. It uses published versions where available; unreleased main-branch work is called out explicitly.

Data date: 2026-09-28

Session boundary: chdb-core allows only one active data path per process. “Multi-connection same path” means a binding can open multiple connections on the same data path; concurrent different data paths are uniformly unsupported and require closing before switching.

Arrow implementation differences: Python and Node primarily expose Arrow IPC bytes and then convert into language objects. Go raw queries can request Arrow output bytes, but its database/sql row path is Parquet-based rather than a typed Arrow API. Rust 2.0 main uses the Arrow C Data Interface, can stream RecordBatch values directly, and supports Arrow bulk insert. Java V1 currently uses RowBinaryWithNamesAndTypes decoded into JDBC ResultSet and does not expose an Arrow Java API.

Streaming note: The user-facing stream differs by binding. Go streams formatted result chunks and its SQL driver reads Parquet chunks; Rust can consume result streams, Arrow batch streams, and streaming inserts; Java exposes a forward-only JDBC ResultSet; Node/WASM expose async streams; Ruby/Zig expose chunked fetch APIs at the binding layer.

Notable feature note: Python DataStore is a pandas-like lazy execution data layer; Node L3 Kysely-style primitives target typed SQL builder use cases; Go’s SQL driver API means it integrates with the standard Go database/sql package; Rust’s Arrow C Data API means Arrow is a first-class data path, not just an output bytes format.

License

Apache 2.0, see LICENSE for more information.

Acknowledgments

chDB is mainly based on ClickHouse [^1] for trade mark and other reasons, I named it chDB.

Contact

• Discord: https://discord.gg/D2Daa2fM5K
• Email: [email protected]
• Twitter: @chdb

[^1]: ClickHouse® is a trademark of ClickHouse Inc. All trademarks, service marks, and logos mentioned or depicted are the property of their respective owners. The use of any third-party trademarks, brand names, product names, and company names does not imply endorsement, affiliation, or association with the respective owners.