No more messy f-strings: Type-safe fluent SQL for ClickHouse.

Day 08 of the WClickHouse Open-Source Engineering Series.

Building dynamic analytical queries by stitching f-strings together is an accident waiting to happen. WClickHouse QueryBuilder gives you fluent, safe SQL composition.

The Pain Points We Faced

• Brittle multi-line SQL strings full of dangerous f-string formatting and syntax typos
• SQL injection risks from unescaped dynamic query parameters
• Difficult code reusability when composing dynamic dashboards with conditional filters

The Implementation

from wclickhouse import QueryBuilder

qb = QueryBuilder()
query, params = (
    qb.table("orders")
    .select(["region", "count() as total_orders", "sum(amount) as revenue"])
    .where("status = :status", status="completed")
    .where("amount > :min_amount", min_amount=100)
    .group_by(["region"])
    .having("revenue > :min_rev", min_rev=10000)
    .order_by("revenue", ascending=False)
    .limit(10)
    .build()
)

Why This Architecture Wins

• Chained API: Build queries fluently with select(), where(), group_by(), order_by().
• Injection Protected: Parameters escaped and validated automatically.
• Advanced Operators: Native support for joins, union_all, and subqueries.

Verification & Status

Tested and verified against live ClickHouse server instances with 95%+ test coverage. Built for Python 3.9 through 3.14 with Apache Arrow and Pydantic v2.

• GitHub: https://github.com/wisrovi/wclickhouse
• PyPI: https://pypi.org/project/wclickhouse

ClickHouse #Python #DataEngineering #OLAP #BigData #Wisrovi