runic-ogm

runic.ogm — Graph OGM for Cypher Databases

runic.ogm is a lightweight, SQLModel-inspired OGM for property-graph databases. You declare nodes and edges as typed Python classes, then create, read, relate, and query them through a Session — without hand-writing Cypher. It targets FalkorDB first and also runs on Neo4j, Memgraph, ArcadeDB, and Apache AGE through a pluggable driver layer.

Three pillars, each with a runnable example and a reference:

Pillar	What it covers	Start here
Mapping	Node/Edge classes, Field(), defaults, PK, indexes, native types	examples/mapping.py
Relations	Relation(), lazy/eager loading, edge models, relate(), polymorphism	examples/relations.py
Query builder	select(), filters, traversal, aggregation, search	examples/query_builder.py

For the full API surface (every Field/Relation parameter, all Session, Repository, and QueryBuilder methods, drivers, exceptions) read references/api-reference.md. For task-oriented recipes and gotchas read references/cookbook.md.

The snippets below omit the # type: ignore / # noqa comments the repo's own examples carry. Those exist only because Field()/Relation() return Any and the descriptor comparison operators (User.age > 18) confuse some type checkers. The code is correct as written; add the ignores only if your checker complains.

---

Quick start

All runic.ogm imports come from runic.ogm directly. Session, Repository, select, and their methods (add, commit, flush, scalars, relate, unrelate, query, count, all_rows, etc.) are runic.ogm-native API — not from SQLAlchemy or any other ORM. Never import from runic.ogm.orm.* — the package root re-exports everything.

from runic.ogm import (
    Field, Node, Edge, Relation,
    Session, AsyncSession,
    Repository,
    select,
    count, avg, sum_,
)
from runic.ogm.driver.factory import create_driver

class User(Node, labels=["User"]):
    id: str = Field(primary_key=True)
    name: str
    email: str = Field(unique=True)
    active: bool = True

driver = create_driver("falkordb", host="localhost", port=6379, graph="app")

with Session(driver) as session:
    session.add(User(id="u1", name="Alice", email="[email protected]"))
    session.commit()

    alice = session.get(User, "u1")     # read by primary key
    alice.name = "Alice B."             # mutation marks the entity dirty
    session.commit()                    # flushes the SET automatically

driver.close()