ActiveGraph ORM¶

ActiveGraph-style ORM for typed knowledge-graph nodes.

Auto-generated docs

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

node_type decorator¶

Symbol	Signature	Description
`@node_type`	`@node_type(label: str, *, fields: dict[str, type], extends: list[str] \\| type \\| None = None, unique: list[tuple[str, ...]] \\| None = None)`	Register a Python class as a Trails node type with typed fields

Every @node_type-decorated class inherits from Model. Key class and instance methods:

Symbol	Signature	Description
`Model.find`	`cls.find(ctx, id_or_iri: str) -> Model \\| None`	Look up a single instance by id or full IRI
`Model.where`	`cls.where(q_nodes: Q, *filters) -> QueryBuilder`	Start a filtered query (returns a `QueryBuilder`)
`Model.annotate`	`cls.annotate(**spec: Aggregate) -> QueryBuilder`	Start a query with aggregation annotations
`.save`	`.save(ctx, *, force: bool = False) -> bool`	Upsert instance; returns `True` if IRI existed (update), `False` on insert

Chained query builder returned by Model.where().

Symbol	Signature	Description
`.where`	`.where(q_nodes: Q, *filters) -> QueryBuilder`	Add filters (AND with existing)
`.annotate`	`.annotate(**spec: Aggregate) -> QueryBuilder`	Add aggregation annotations
`.order_by`	`.order_by(field: str, *, descending: bool = False) -> QueryBuilder`	Set result ordering
`.limit`	`.limit(n: int) -> QueryBuilder`	Cap number of results
`.offset`	`.offset(n: int) -> QueryBuilder`	Skip first N results
`.fetch`	`.fetch(ctx) -> list[Model]`	Execute query and return hydrated instances
`.count`	`.count(ctx) -> int`	Return number of matching subjects
`.exists`	`.exists(ctx) -> bool`	Return `True` if at least one match exists
`.delete`	`.delete(ctx) -> int`	Delete matching instances; returns count removed
`.values`	`.values(*fields: str) -> QueryBuilder`	Project to dict rows with named fields
`.values_list`	`.values_list(*fields: str, flat: bool = False) -> QueryBuilder`	Project to tuple rows (flat=True for single-field scalar list)

Composable filter node for OR / NOT / nested logic in queries.