Metadata-Version: 2.4
Name: clickhouse_orm
Version: 3.0.1
Summary: A simple ORM for working with the Clickhouse database. Maintainance fork of infi.clickhouse_orm.
Author-email: Oliver Margetts <oliver.margetts@gmail.com>
Description-Content-Type: text/markdown
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pytz
Requires-Dist: docker==7.1.0 ; extra == "dev"
Requires-Dist: pytest==9.0.2 ; extra == "dev"
Requires-Dist: ruff==0.14.14 ; extra == "dev"
Project-URL: Homepage, https://github.com/SuadeLabs/clickhouse_orm
Project-URL: Repository, https://github.com/SuadeLabs/clickhouse_orm
Provides-Extra: dev

A fork of [infi.clikchouse_orm](https://github.com/Infinidat/infi.clickhouse_orm) aimed at more frequent maintenance and bugfixes.

[![Tests](https://github.com/SuadeLabs/clickhouse_orm/actions/workflows/python-test.yml/badge.svg)](https://github.com/SuadeLabs/clickhouse_orm/actions/workflows/python-test.yml)
![PyPI](https://img.shields.io/pypi/v/clickhouse_orm)

Introduction
============

This project is simple ORM for working with the [ClickHouse database](https://clickhouse.yandex/).
It allows you to define model classes whose instances can be written to the database and read from it.

Let's jump right in with a simple example of monitoring CPU usage. First we need to define the model class,
connect to the database and create a table for the model:

```python
from clickhouse_orm import Database, Model, DateTimeField, UInt16Field, Float32Field, Memory, F

class CPUStats(Model):

    timestamp = DateTimeField()
    cpu_id = UInt16Field()
    cpu_percent = Float32Field()

    engine = Memory()

db = Database('demo')
db.create_table(CPUStats)
```

Now we can collect usage statistics per CPU, and write them to the database:

```python
import psutil, time, datetime

psutil.cpu_percent(percpu=True) # first sample should be discarded
while True:
    time.sleep(1)
    stats = psutil.cpu_percent(percpu=True)
    timestamp = datetime.datetime.now()
    db.insert([
        CPUStats(timestamp=timestamp, cpu_id=cpu_id, cpu_percent=cpu_percent)
        for cpu_id, cpu_percent in enumerate(stats)
    ])
```

Querying the table is easy, using either the query builder or raw SQL:

```python
# Calculate what percentage of the time CPU 1 was over 95% busy
queryset = CPUStats.objects_in(db)
total = queryset.filter(CPUStats.cpu_id == 1).count()
busy = queryset.filter(CPUStats.cpu_id == 1, CPUStats.cpu_percent > 95).count()
print('CPU 1 was busy {:.2f}% of the time'.format(busy * 100.0 / total))

# Calculate the average usage per CPU
for row in queryset.aggregate(CPUStats.cpu_id, average=F.avg(CPUStats.cpu_percent)):
    print('CPU {row.cpu_id}: {row.average:.2f}%'.format(row=row))
```

This and other examples can be found in the `examples` folder.

To learn more please visit the [documentation](docs/toc.md).

