clickhouse_df

A lightweight ClickHouse helper package focused on DataFrame workflows.

It provides:

• connect: thread-local ClickHouse client management
• to_pandas: run SQL and return pandas.DataFrame
• to_polars: run SQL and return polars.DataFrame
• raw_ck_download: export query results to Parquet via ClickHouse client

Install from GitHub (uv)

Replace <owner> with your GitHub account or org.

uv add "git+https://github.com/<owner>/clickhouse_df.git"

Pin to a tag:

uv add "git+https://github.com/<owner>/clickhouse_df.git@v0.1.5"

You can also install directly into an environment:

uv pip install "git+https://github.com/<owner>/clickhouse_df.git"

Quick Start

from clickhouse_df import connect, to_pandas, to_polars

conn = connect(["127.0.0.1:9000"], user="default", password="")

df_pd = to_pandas("SELECT number FROM system.numbers LIMIT 5", conn)
df_pl = to_polars("SELECT number FROM system.numbers LIMIT 5", conn)

Raw export to Parquet:

from clickhouse_df import raw_ck_download

settings = {
    "urls": ["127.0.0.1:9000"],
    "user": "default",
    "password": "",
}

raw_ck_download("SELECT number FROM system.numbers LIMIT 5", "./sample.parquet", settings)

Development (uv)

uv sync
uv run ruff format --check .
uv run ruff check .
uv run python -m unittest discover -s tests
uv build

Versioning

Project version is controlled in __version__.py.

License

MIT