infi.clickhouse-orm

What it is and what it does

infi.clickhouse_orm is a lightweight Python ORM for ClickHouse, a columnar analytics database. It provides a declarative model system where you define table schemas as Python classes with typed fields (DateTimeField, UInt16Field, Float32Field, etc.), then insert and query data through a Python API. The package handles the connection to ClickHouse, table creation, bulk inserts, and result mapping back to model instances.

You can query using a fluent query builder (filter, aggregate, count) or drop into raw SQL when needed. The example in the documentation shows defining a CPU statistics model, collecting data in a loop, and then analyzing it with both query-builder and aggregation patterns. It has no external runtime dependencies, making installation straightforward, but the project has been dormant since 2022-11-29, so compatibility with recent ClickHouse versions or Python releases is not guaranteed.

Use it for:

• Define ClickHouse table schemas as Python classes and create tables programmatically without raw DDL.
• Bulk insert time-series or event data into ClickHouse from Python applications.
• Query ClickHouse tables using a Python query builder instead of writing SQL strings directly.
• Map ClickHouse query results back to typed Python model instances for easier data handling.
• Prototype or migrate analytics workloads that use ClickHouse as the backend.

Worth the install?

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

An ORM for ClickHouse that lets you define model classes, insert records, and query the database using a Python API or raw SQL.

Yes, if you are actively using ClickHouse and prefer a Python ORM interface over raw SQL or another client library. The low install friction and permissive license are advantages. However, dormant maintenance since 2022-11-29 is a real concern—verify that it works with your ClickHouse server version and Python release before committing to it in production.

Install

infi-clickhouse-orm on PyPI

pip install infi-clickhouse-orm

uv add infi-clickhouse-orm

poetry add infi-clickhouse-orm

Installing infi.clickhouse-orm

Before you install

Low install friction with no runtime dependencies. Maintenance is dormant—last release was 2022-11-29, over 1354 days ago, though the repository remains active with a recent commit on 2024-06-03.

License in practice

BSD license is permissive, allowing commercial and private use with minimal restrictions.

Quickstart

from infi.clickhouse_orm import Database, Model, DateTimeField, UInt16Field, Float32Field, Memory

class CPUStats(Model):
    timestamp = DateTimeField()
    cpu_id = UInt16Field()
    cpu_percent = Float32Field()
    engine = Memory()

db = Database('demo')
db.create_table(CPUStats)
queryset = CPUStats.objects_in(db)
print(queryset.count())

Verify before relying

• Whether the package works with current ClickHouse server versions and modern Python releases.
• Whether dormant maintenance means bug fixes or security patches are unlikely if issues arise.
• Compatibility with ClickHouse protocol changes since the last release in 2022-11-29.

Package facts

Evidence: infi.clickhouse_orm-2.1.3-py3-none-any.whl

Tags

More Python Modules packages