Quickstart¶

Install runic, connect to FalkorDB, define a model, and persist it — all on this page.

Installation¶

uv add runic-py    # or: pip install runic-py

FalkorDB must be running. The simplest way for local development:

docker run -p 6379:6379 falkordb/falkordb

Hello, Node¶

from falkordb import FalkorDB

from runic.orm import Field, Node, Repository, Session

# 1. Define a model
class Language(Node, labels=["Language"]):
    id: str = Field()
    title: str = Field()
    code: str = Field(unique=True)

# 2. Connect
db = FalkorDB(host="localhost", port=6379)
graph = db.select_graph("myapp")

# 3. Create
with Session(graph) as session:
    lang = Language(id="en", title="English", code="en")
    session.add(lang)
    session.commit()
    print(lang.id)   # "en"

# 4. Read
with Session(graph) as session:
    repo = Repository(session, Language)
    all_langs = repo.find_all()
    english = session.get(Language, "en")

# 5. Update
with Session(graph) as session:
    en = session.get(Language, "en")
    en.title = "English (UK)"      # marks _dirty = True
    session.commit()               # MERGE … SET on flush

# 6. Delete
with Session(graph) as session:
    en = session.get(Language, "en")
    session.delete(en)
    session.commit()

Key takeaways¶

Models inherit from Node and declare fields with Field().
The Session is the unit of work. All mutations (add, delete) go through it.
Repository handles reads.
session.commit() = flush() + clear pending/deleted sets.