chdb

library4.3.0pypypi✓ verified 25d ago

chDB is an in-process OLAP SQL Engine powered by ClickHouse, enabling users to embed a powerful analytical database directly within their Python applications. It allows running SQL queries on various data formats (Parquet, CSV, JSON, Pandas DataFrames) without needing a separate database server. Currently at version 4.1.6, chDB maintains an active development and release cadence, frequently adding features and improvements.

database data serialization

pip install chdb

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CHDB

chdb

databasepythonv4.3.0

Install

14.8s avg

Import

284ms

Disk

948MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.7.2 · 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.95 runs

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

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 14.8s · import 0.284s · 872MB

948MB installed

● package 948MB

Code

Verified usage

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

chdb

✓ import chdb

Session

✓ from chdb import session as chs

Used for stateful sessions to maintain database state across queries.

dbapi

✓ import chdb.dbapi as dbapi

For using chDB with the Python DB-API 2.0 interface.

DataStore

✓ from chdb.datastore import DataStore

✗ import chdb.datastore as pd

While `import chdb.datastore as pd` is often suggested for a Pandas-like API, directly importing `DataStore` or `chdb` for `chdb.query` is the primary usage for the core engine features. The `as pd` pattern aims for a drop-in replacement, which might mask `chdb`'s distinct behaviors.

This quickstart demonstrates how to execute a basic SQL query using `chdb.query` and receive the results directly as a Pandas DataFrame. It also shows how to query an existing Pandas DataFrame using ClickHouse SQL syntax via the `python(df_name)` table function.

import chdb import pandas as pd # Run a simple SQL query and get results as a Pandas DataFrame result_df = chdb.query("SELECT 1 as id, 'Hello chDB!' as message, version() as chdb_version", "DataFrame") print("Query Result (DataFrame):\n", result_df) # Query an existing Pandas DataFrame directly data = {'col1': [1, 2, 3], 'col2': ['A', 'B', 'C']} mypandas_df = pd.DataFrame(data) sql_on_df = "SELECT col1, upper(col2) FROM python(mypandas_df) WHERE col1 > 1" queried_df_from_pandas = chdb.query(sql_on_df, "DataFrame") print("\nQuery Result from Pandas DataFrame (DataFrame):\n", queried_df_from_pandas)

chdb --version

Debug

Known issues

gotchachDB is an in-process engine and shares memory with your application. Running complex queries that process large datasets (e.g., aggregating 10GB on an 8GB RAM machine) can lead to out-of-memory crashes for the entire Python process, unlike server-side databases that can spill to disk.

fix

Monitor memory usage for complex queries. For extremely large datasets, consider pre-processing or using a full ClickHouse server. Optimize SQL queries to reduce memory footprint where possible.

affects: All versions

gotchachDB operates in a single process and lacks built-in authentication, multi-tenancy, or fine-grained resource limits per user. This makes it unsuitable for multi-user applications or highly concurrent environments where resource isolation and access control are critical.

fix

Design your application with chDB as a single-user, embedded analytical tool. Implement access control and resource management at the application layer if necessary, or opt for a full ClickHouse server for multi-tenant scenarios.

affects: All versions

gotchaWhen using the DataStore (Pandas-compatible API) with chained operations in chDB v4.x, each intermediate step can materialize a new DataFrame in memory. This can lead to higher memory consumption than anticipated for large datasets, potentially negating some performance benefits.

fix

Be mindful of chained DataFrame operations. For large datasets, consider explicitly performing operations that avoid intermediate materialization or breaking down complex chains into optimized SQL queries where possible.

affects: 4.0.0 and later

breakingIn version 4.1.0, the `chdb` package was decoupled from `chdb-core`. While this was primarily an architectural change for packaging, users who had deep integrations or relied on specific internal structures related to `chdb-core` might experience breaking changes.

fix

Review your code for any direct references to `chdb-core` components. Ensure your environment correctly resolves dependencies after upgrading to 4.1.0 or later.

affects: Prior to 4.1.0

gotchaVersions prior to 4.1.0 were known to experience crashes when exiting the Python process, particularly with persistent sessions.

fix

Upgrade to chDB version 4.1.0 or newer to benefit from the fix for exit-related crashes.

affects: Prior to 4.1.0

gotchaAn issue in versions prior to 4.1.4 could lead to a broken module after upgrading, due to a missing `chdb/__init__.py` file.

fix

Ensure you are using chDB version 4.1.4 or newer to avoid potential module import issues after package upgrades.

affects: Prior to 4.1.4

Errors

Common errors & fixes

Python process crashed (Out of Memory / Segmentation fault)

chDB runs in-process and shares memory with the Python application. Queries that attempt to process or aggregate data larger than available RAM can cause the entire Python process to crash due to out-of-memory conditions or segmentation faults.

fix

Reduce the dataset size, process data in smaller chunks, or increase the available memory for the Python process. For datasets exceeding available RAM, consider using a ClickHouse server which can spill to disk.

ImportError: If pyarrow or pandas aren't installed.

The chdb.query function, when used with output_format="DataFrame" or output_format="ArrowTable", requires the 'pandas' or 'pyarrow' library, respectively, to be installed.

fix

Install the missing dependency using pip: `pip install pandas` or `pip install pyarrow`.

Code: X. DB::Exception: Syntax error: Syntax error near 'KEYWORD'

The SQL query provided contains syntax errors, uses reserved keywords without proper escaping, or attempts to use a function that is not supported or enabled in the underlying ClickHouse engine version embedded in chDB.

fix

Review the SQL query for typos, ensure correct ClickHouse SQL syntax, use backticks (`) to escape reserved keywords if used as identifiers, or check the chDB/ClickHouse documentation for supported functions and versions.

Code: 82. DB::Exception: Database default already exists. (DATABASE_ALREADY_EXISTS)

This error occurs when a chdb.Session attempts to create a database (e.g., `CREATE DATABASE default;`) that already exists, particularly when a session is re-initialized with persistent storage in the same location.

fix

Check if the database exists before attempting to create it (e.g., `CREATE DATABASE IF NOT EXISTS default;`), or use a temporary in-memory session if persistence is not required for that specific operation.

DB::Exception: Cannot append data in format Parquet to file, because this format doesn't support appends. (CANNOT_APPEND_TO_FILE)

The Parquet file format, by default, does not support appending data directly. When using a File table engine with Parquet format in ClickHouse (and thus chDB), subsequent INSERT statements will fail if they try to append to the same file.

fix

Enable the `engine_file_allow_create_multiple_files` setting before inserting to allow ClickHouse to create new files for each insert: `chdb.query("SET engine_file_allow_create_multiple_files = 1;")` before your INSERT statements.

Upgrade

Version history

4.3.0latest on PyPI · released Aug 17, 2026

Audit

Dependencies

chdb-corerequiredchDB builds upon chdb-core, which provides the underlying ClickHouse engine. While `pip install chdb` handles this automatically, awareness can be useful for debugging or advanced scenarios.

pandasoptionalHighly recommended for seamless integration with Pandas DataFrames, including direct querying and results output. Essential for the DataStore API.

pyarrowoptionalRecommended for efficient data exchange and integration with Apache Arrow, especially when working with columnar data formats and DataFrame outputs.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

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

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

homepagehttps://clickhouse.com/chdb ↗

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

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