chdb-core

What it is and what it does

chdb-core is the foundational C++ engine of the chDB ecosystem, bringing ClickHouse's OLAP capabilities into Python as an embedded library. It executes SQL queries directly in your process without running a separate database server, making it suitable for analytics, data exploration, and batch processing workflows. The package supports stateless one-shot queries, stateful sessions with connection management, streaming for constant-memory processing, and Python DB-API 2.0 compliance.

It depends on pandas and pyarrow for data interchange and integrates with multiple formats—Parquet, CSV, JSON, Arrow, ORC, and 60+ others—allowing you to query files or in-memory data structures directly. The engine minimizes data copying between C++ and Python using memory views, and provides features like parameterized queries, user-defined functions, and query statistics. Wheels are pre-built for Python 3.9+ on Linux and macOS (both x86_64 and ARM64), reducing compile-time friction.

Use it for:

• Query Parquet, CSV, or JSON files directly with SQL without loading them into a DataFrame first.
• Join and aggregate multiple pandas DataFrames using SQL syntax within a Python script.
• Stream large datasets through a query in chunks to maintain constant memory usage.
• Run parameterized SQL queries with variable substitution for dynamic analytics.
• Build analytics pipelines that need fast OLAP-style aggregations without external database infrastructure.

Worth the install?

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

chdb-core is an in-process SQL OLAP engine powered by ClickHouse that runs SQL queries directly in Python without requiring a separate server, supporting multiple input/output formats and DB-API 2.0 compliance.

Yes, if you need serverless SQL analytics in Python. chdb-core is actively maintained, has no known vulnerabilities, and offers genuine value for data exploration and batch processing. Install friction is moderate due to compiled bindings, but pre-built wheels for common platforms mitigate this. The Apache-2.0 license is permissive. Consider it a strong fit for embedded analytics; if you need a higher-level pandas-like API, install the chDB package instead.

Install

chdb-core on PyPI

pip install chdb-core

uv add chdb-core

poetry add chdb-core

Installing chdb-core

Before you install

Medium install friction due to compiled C++ bindings (wheels provided for Python 3.9+ on Linux and macOS x86_64/ARM64). Package is actively maintained with recent releases and no known vulnerabilities.

License in practice

Apache-2.0 is permissive; you can use, modify, and distribute chdb-core freely in commercial and private projects with minimal restrictions.

Quickstart

pip install chdb-core

import chdb

result = chdb.query("SELECT 1, 'hello'")
print(result)

# Query a Parquet file
df = chdb.query('SELECT * FROM file("data.parquet", Parquet)', "DataFrame")

Requires Python 3.9+ on Linux (x86_64 or ARM64) or macOS; no Windows support.

Verify before relying

• Whether chdb-core's performance characteristics and query optimization strategies match your workload requirements.
• Compatibility and integration patterns with existing pandas and pyarrow workflows in your codebase.
• Memory overhead and scalability limits for large datasets in in-process execution.

Package facts

Evidence: chdb_core-26.7.0-cp39-abi3-macosx_10_15_x86_64.whl; chdb_core-26.7.0-cp39-abi3-macosx_11_0_arm64.whl; chdb_core-26.7.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl; chdb_core-26.7.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

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

Tags

More Libraries packages