Knowledge Graph¶

The KG class is the ORM-flavoured handle on the kernel graph store, available as ctx.kg inside capability handlers.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Write operations¶

Symbol	Signature	Description
`.add`	`.add(instance) -> None`	Persist a `@node_type` instance's triples (insert-only). SHACL validation runs before the write
`.save`	`.save(instance) -> bool`	Upsert a `@node_type` instance. Returns `True` when the IRI existed before (update)
`.node`	`.node(*, labels: list[str], properties: dict[str, Any] \\| None = None) -> str`	Create a label-first node and return its minted IRI
`.edge`	`.edge(*, subject: str, label: str, object: str) -> None`	Create a label-first edge triple
`.update`	`.update(sparql: str) -> tuple[int, int]`	Raw SPARQL UPDATE escape hatch

Symbol	Signature	Description
`.find`	`.find(model_cls: type, id_or_iri: str) -> Model \\| None`	Look up a single `@node_type` instance by id or full IRI
`.where`	`.where(model_cls: type, **filters) -> QueryBuilder`	Start a query builder for a model class with optional filters
`.match`	`.match(*, labels: list[str] \\| None = None, types: list \\| None = None, where: dict \\| None = None) -> list[dict]`	Match nodes by label set and/or `@node_type` set with optional filters
`.traverse`	`.traverse(*, subject: str, label: str) -> list[str]`	Walk one edge hop --- return neighbor IRIs reached by the label
`.query`	`.query(sparql: str, *, reason: bool \\| None = None) -> list[dict]`	Raw SPARQL SELECT/ASK escape hatch. `reason=True` materialises RDFS/OWL-RL before executing

Symbol	Signature	Description
`.transaction`	`.transaction() -> Transaction`	Return a write-buffering context manager. Writes land atomically on exit; discarded on exception