Metadata-Version: 2.4
Name: rhei-engine
Version: 1.5.0
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: anyio>=4.13.0
License-File: LICENSE
Summary: Lightweight serverless HTAP engine — Python bindings for the Rhei Rust library
Author-email: ValerioL29 <jiacheng@mewtant.io>
License-Expression: Apache-2.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# rhei-engine

Python bindings for the [Rhei HTAP engine](https://github.com/ValerioL29/Rhei) -- lightweight, serverless Hybrid Transactional/Analytical Processing.

All engine methods are **async** and compatible with **asyncio** and **anyio**.

## Install

```bash
pip install rhei-engine
# or
uv add rhei-engine
```

> **Note**: the package is published as `rhei-engine` on PyPI (the `rhei` name was already taken), but the import name is `rhei`:
> ```python
> import rhei  # not "import rhei_engine"
> ```

## Build from source

```bash
cd python
uv sync
uv run maturin develop
```

## Quick start

```python
import anyio
import rhei

async def main():
    async with await rhei.open(oltp_path="my.db") as engine:
        # Create table and register for CDC replication
        await engine.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
        await engine.register_table(
            rhei.TableSchema("users", [("id", "int64"), ("name", "utf8"), ("age", "int64")], ["id"])
        )

        # Write (routed to OLTP)
        await engine.execute("INSERT INTO users VALUES (1, 'Alice', 30)")

        # Batch write (single transaction, ~35K rows/sec)
        await engine.execute_batch([
            "INSERT INTO users VALUES (2, 'Bob', 25)",
            "INSERT INTO users VALUES (3, 'Charlie', 35)",
        ])

        # Sync CDC to OLAP
        result = await engine.sync_now()
        print(result)  # SyncResult(events=3, inserted=3, ...)

        # Query (auto-routed: aggregates -> OLAP, point queries -> OLTP)
        batches = await engine.query("SELECT AVG(age) FROM users")  # list[pyarrow.RecordBatch]
        print(batches[0].to_pydict())

anyio.run(main)
```

## API

| Method | Description |
|--------|-------------|
| `rhei.open(**kwargs)` | Async factory (non-blocking init) |
| `HtapEngine(config)` | Sync constructor |
| `engine.execute(sql)` | Write statement (OLTP) |
| `engine.execute_batch(stmts)` | Batch writes in single transaction |
| `engine.query(sql)` | Auto-routed query -> `list[pyarrow.RecordBatch]` |
| `engine.query_olap(sql)` | Force OLAP query |
| `engine.sync_now()` | Sync CDC events to OLAP |
| `engine.register_table(schema)` | Register table for replication |
| `engine.add_column(t, c, type)` | Add column + rebuild CDC triggers |
| `engine.drop_column(t, c)` | Drop column |
| `engine.initial_sync(table)` | Bulk OLTP -> OLAP load |
| `engine.shutdown()` | Cleanup (resources released on GC) |

## License

Apache-2.0

