---
id: chdb-core
version: "26.7.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# chdb-core — chDB is an in-process OLAP SQL Engine powered by ClickHouse

License: permissive · Maintenance: active · Downloads: 217.5K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 217.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

in-process SQL OLAP engine, clickhouse python library, embedded SQL query engine, serverless analytics database, parquet csv json sql query, python olap analytics, db-api sql engine, embedded-analytics, olap-engine, sql-query

[View on SkillFed](https://skillfed.io/packages/chdb-core) · [View on PyPI](https://pypi.org/project/chdb-core/)