infi.clickhouse-orm

2.1.3 verified Fri May 01 auth: no python

A Python ORM-like library for interacting with ClickHouse databases, providing high-level abstractions for creating, querying, and manipulating data. Current version: 2.1.3. Release cadence is irregular.

pip install infi-clickhouse-orm

Common errors

error ModuleNotFoundError: No module named 'clickhouse_orm' ↓

cause Importing using old module name, but the package is installed as infi-clickhouse-orm.

fix

Use 'from infi.clickhouse_orm import ...' instead.

error AttributeError: 'Database' object has no attribute 'create_table' ↓

cause Attempting to use create_table before establishing a connection or using an older API version.

fix

Ensure you have created a Database instance with a valid db_url. In version 2.x, use db.create_table(ModelClass).

error clickhouse_driver.errors.ServerException: Code: 60, e.displayText() = DB::Exception: Table default.persons doesn't exist ↓

cause The table does not exist or the tablename attribute is not set correctly on the Model.

fix

Set tablename explicitly on the model class to match the existing table name or run create_table() first.

Warnings

gotcha Table names are case-sensitive and must match the database schema. The ORM does not automatically lowercase or uppercase table names. ↓

fix Explicitly set tablename attribute in Model subclasses to match existing tables.

breaking In version 2.0.0, the import path changed from clickhouse_orm to infi.clickhouse_orm. Old code using from clickhouse_orm import ... will break. ↓

fix Change import statements to from infi.clickhouse_orm import ...

gotcha The insert() method expects a list of model instances; inserting a single instance without wrapping in a list causes a TypeError. ↓

fix Always pass a list: db.insert([instance])

Imports

Database
wrong
```
from clickhouse_orm import Database
```
correct
```
from infi.clickhouse_orm import Database
```
The package is installed as infi-clickhouse-orm but imported as infi.clickhouse_orm
Model
```
from infi.clickhouse_orm import Model
```

Quickstart

Basic usage: define a model, create table, insert and query data.

from infi.clickhouse_orm import Database, Model, StringField, Int32Field

class Person(Model):
    name = StringField()
    age = Int32Field()
    tablename = 'persons'

# Connect to ClickHouse (adjust host/port as needed)
db = Database('default', db_url='http://localhost:8123/')
db.create_table(Person)

# Insert a record
person = Person(name='Alice', age=30)
db.insert([person])

# Query
results = db.select('SELECT * FROM persons')
for row in results:
    print(row.name, row.age)