chDB

Use it when you want ClickHouse performance in a script, a notebook, or an application, and running a server would be overkill.

What it gives you#

The ClickHouse SQL engine, in-process.
Input and output in Parquet, CSV, JSON, Arrow, ORC, and 70+ other formats.
No external database installation and no dependencies to manage.

Bindings exist for Python, Go, Rust, Node.js, Bun, C, and C++. Python is the most complete.

Install and run a query#

python -m venv .venv
source .venv/bin/activate

pip install "chdb>=2.0.2"

import chdb
 
result = chdb.query("SELECT 1 AS x, 'hello' AS y", "CSV")
print(result)

The second argument selects the output format. "DataFrame" returns a pandas.DataFrame, and "ArrowTable" returns a pyarrow.Table.

Query files without loading them#

Table functions work exactly as they do in the server, so a Parquet file on disk or in S3 is queryable directly:

chdb.query("SELECT count() FROM file('data.parquet', Parquet)", "Pretty")

chdb.query(
  """
  DESCRIBE s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )
  SETTINGS describe_compact_output=1
  """
)

Query a Pandas DataFrame#

chDB reads DataFrames from your process directly through the Python() table function:

chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)

This is the fastest path from a DataFrame to a ClickHouse aggregation, since nothing is serialized over a network.

Persistent sessions#

A Session gives you real databases and tables stored on disk, so state survives between runs:

from chdb import session as chs
 
sess = chs.Session("gettingStarted.chdb")
sess.query("CREATE DATABASE IF NOT EXISTS youtube")
sess.query("""
  CREATE TABLE youtube.dislikes
  ORDER BY fetch_date
  EMPTY AS
  SELECT *
  FROM s3('https://example.com/data.json', 'JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
""")

Build queries safely#

chDB does not yet support query parameters. Interpolating variables you control is fine, but never interpolate user-provided input — the query is open to SQL injection.

When you need parameter binding, use a ClickHouse server and the HTTP interface, which supports typed {name:Type} parameters.

chDB or a server?#

Use chDB for local analysis, notebooks, CI data checks, embedded analytics, and single-process tools where the data fits on one machine.

Use a server when several clients query the same data, when data outgrows one machine, when you need replication and backups, or when you need parameter binding and access control. See self-hosting vs Cloud.

Integrations overview — clients and connectors for the server
HTTP interface — the server equivalent for other languages
Install ClickHouse — when you outgrow in-process

Updated Aug 15, 2026