runic-ogm

Subclass Node with a labels list and declare typed fields using bare annotations or Field() for options like primary_key, unique, and index. Edge property models subclass Edge with a type string. Constructors are keyword-only, and datetime and Enum fields get converters automatically.

Declare a Relation with relationship, direction, target, and an edge_model, then call session.relate(source, field, target, edge=EdgeInstance) which uses MERGE semantics and updates properties in place. Read edge properties via a traversal with edge_alias and session.all_with_edges().

Yes, runic.ogm runs on FalkorDB, Neo4j, Memgraph, ArcadeDB, and Apache AGE through a pluggable driver layer created with create_driver. Models and queries stay unchanged, but Vector, GeoLocation, and interned types are FalkorDB-only, and search features vary by backend.

AsyncSession has no lazy loading, so touching an unloaded relation raises LazyLoadError. You must eager-load with await session.get(Cls, pk, fetch=[...]) or use a traversal query, and await coroutine methods like commit, relate, and scalars.

Use fetch=[...] on session.get() to eager-load one entity's relations in a single query. For collections of parents, prefer one traversal query with all_with_edges() over looping with lazy access, which fires one query per entity.

Drop to session.execute() or Repository.cypher() only for what the builder cannot express, such as edge-heavy reads, set operations, or bulk writes. Always parameterize values with $name placeholders rather than string formatting.