chdb-core

library26.5.0pypypi✓ verified 85d ago

chDB-core is an in-process OLAP SQL Engine, embedding the powerful analytical capabilities of ClickHouse directly within Python applications. It allows users to execute high-performance SQL queries without the need for a separate ClickHouse server installation or network communication. The library maintains an active development and release cadence, with version 26.1.0 being the current stable release.

database data

pip install chdb-core

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CHDB-CORE

chdb-core

databasepythonv26.5.0

Install

13.2s avg

Import

551ms

Disk

419MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 13.2s · import 0.551s · 820MB

419MB installed

● package 419MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

query

✓ from chdb import query

✗ import chdb

connect

✓ from chdb import connect

✗ import chdb

chdb_version

✓ from chdb import chdb_version

✗ import chdb

This quickstart demonstrates how to perform a basic SQL query using the `chdb.query` function and how to get results in different formats, including a Pandas DataFrame. The `chdb-core` package exposes its primary functionalities via the `chdb` module.

import chdb # Execute a simple SQL query result = chdb.query("SELECT 'Hello, chDB-core!' as message, version() as chdb_version", "Pretty") print(result) # Example with DataFrame output (requires pandas to be installed) try: import pandas as pd df = chdb.query("SELECT number, number * 2 AS double FROM numbers(5)", "DataFrame") print(df) print(type(df)) except ImportError: print("Pandas not installed. Skipping DataFrame example.")

Debug

Known issues

breakingThe `chdb` project has been split into two packages: `chdb-core` (this package) and `chdb`. `chdb-core` provides the low-level C++ engine and SQL interfaces (`query`, `dbapi`). If you were previously using `chdb` for its higher-level Pandas-compatible DataStore API, you must now explicitly install `chdb` (i.e., `pip install chdb`) instead of, or in addition to, `chdb-core`.

fix

Ensure you install the correct package: `pip install chdb-core` for core SQL engine, or `pip install chdb` for DataStore API built on `chdb-core`.

affects: Introduced in v26.1.0 and subsequent versions.

gotchaAs an in-process OLAP engine, chDB-core shares the application's memory space. Running queries that process or aggregate very large datasets (e.g., 10GB on an 8GB RAM machine) can lead to out-of-memory errors and application crashes, unlike a standalone ClickHouse server which might spill to disk. Similarly, long-running queries can block the entire application process.

fix

Optimize queries to reduce memory footprint, process data in chunks (streaming), or consider using a separate ClickHouse server for extremely large or long-running tasks. Monitor memory usage carefully for in-process deployments.

affects: All versions

gotchaUser-Defined Functions (UDFs) must be stateless and pure Python functions. All required modules for a UDF must be imported *inside* the UDF function itself, not at the module level. Input arguments are always treated as strings, and the default return type is also a string, requiring explicit type conversions within the UDF for numerical operations.

fix

Design UDFs as pure functions without side effects. For example, `def my_udf(arg1, arg2): import json; return str(json.loads(arg1)['key'])`. Explicitly cast string inputs to appropriate types (e.g., `int(lhs)`, `float(rhs)`) and cast the result back to string if not specifying a return type.

affects: All versions

Upgrade

Version history

26.5.0latest on PyPI · released Jun 8, 2026

Audit

Dependencies

pythonrequiredRequired runtime environment

pandasoptionalFor DataFrame input/output formats and higher-level DataStore API (if 'chdb' package is also used)

pyarrowoptionalFor Apache Arrow input/output formats

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chdb-io/chdb-core ↗

packagehttps://pypi.org/project/chdb-core/ ↗

homepagehttps://clickhouse.com/chdb ↗

docshttps://chdb.readthedocs.io/en/latest/index.html ↗

changeloghttps://github.com/chdb-io/chdb-core/releases ↗