---
id: infi-clickhouse-orm
version: "2.1.3"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# infi.clickhouse-orm — A Python library for working with the ClickHouse database

License: permissive · Maintenance: dormant · Downloads: 260.4K/mo

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

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

- License: BSD (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 260.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

clickhouse orm python, clickhouse database client, python clickhouse models, clickhouse query builder, clickhouse data mapping, clickhouse insert records, clickhouse table abstraction, clickhouse, orm, analytics

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