orionis.orm.relations.Relation

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Relation(ModelQueryBuilder[TRelated], IRelation): (source)

Known subclasses: orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Constructor: Relation(parent, related)

View In Hierarchy

Base class for every query builder bound to a parent model instance.

A relationship is a regular ModelQueryBuilder targeting the related model, pre-constrained to the rows belonging to a specific parent instance. Concrete kinds (hasOne, hasMany, belongsTo, belongsToMany, and future polymorphic or through-relations) only need to implement the template methods below; the full fluent query API is inherited for free.

Class Method	`noConstraints`	Build a relationship instance without its single-parent constraint.
Method	`__await__`	Allow `await` directly on a relationship without a terminal.
Method	`__init__`	Bind a relationship query builder to its parent instance.
Method	`addConstraints`	Constrain the query to the bound parent instance.
Method	`addEagerConstraints`	Constrain the query to every parent instance of an eager batch.
Async Method	`getEager`	Execute the relationship query assembled for eager loading.
Async Method	`getResults`	Execute the relationship query for its bound parent instance.
Method	`match`	Group eager-loaded results and attach them to their parents.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_eager_keys_empty`	Undocumented
Instance Variable	`_parent`	Undocumented

Inherited from ModelQueryBuilder:

Method	`__getattr__`	Expose the local scopes declared by the bound model.
Method	`_beforeExecute`	Apply the global scopes and the soft delete filter once.
Method	`_connection`	Resolve the database connection for the bound model.
Method	`_defaultTimestampColumn`	Return the column `latest` and `oldest` default to.
Async Method	`_eagerLoad`	Resolve every pending eager-loaded relationship for a result set.
Method	`_existsColumns`	Return the projection used by existence probes.
Async Method	`_fireRetrieved`	Dispatch the `retrieved` event for freshly hydrated models.
Method	`_prepareUpdate`	Refresh the update timestamp of a mass update payload.
Method	`_relationErrorMessage`	Build the error message for an unresolvable relationship name.
Method	`_serializeValues`	Apply the model casts before values reach the database.
Method	`clone`	Return an independent copy of this builder.
Async Method	`delete`	Delete the matched rows, honoring soft deletes when enabled.
Async Method	`find`	Retrieve a model by its primary key.
Async Method	`findOrFail`	Retrieve a model by primary key or raise when absent.
Async Method	`first`	Execute the query and hydrate only the first matching row.
Async Method	`firstOrFail`	Return the first matching row or raise when none exists.
Async Method	`forceDelete`	Delete the matched rows permanently, ignoring soft deletes.
Async Method	`get`	Execute the query and hydrate every matching row.
Method	`load`	Eager load the given relationships; alias of `withRelations`.
Method	`onlyTrashed`	Restrict the query to soft deleted rows.
Async Method	`paginate`	Execute the query returning a length-aware page of results.
Async Method	`pluck`	Return one column of every matching row.
Async Method	`restore`	Restore every soft deleted row matched by the query.
Method	`scope`	Apply a local scope by name.
Async Method	`value`	Return a single column value of the first matching row.
Method	`withoutGlobalScope`	Disable one global scope for this query.
Method	`withoutGlobalScopes`	Disable several global scopes, or every one of them.
Method	`withoutTrashed`	Exclude soft deleted rows; the default behavior.
Method	`withRelations`	Eager load the given relationships alongside the query.
Method	`withTrashed`	Include soft deleted rows in the query results.
Instance Variable	`_connection_name`	Undocumented
Instance Variable	`_eager_loads`	Undocumented
Instance Variable	`_meta`	Undocumented
Instance Variable	`_model`	Undocumented
Instance Variable	`_scopes_applied`	Undocumented
Instance Variable	`_trashed_mode`	Undocumented
Instance Variable	`_without_scopes`	Undocumented

Inherited from QueryBuilderBase (via ModelQueryBuilder):

Static Method	`_boundaryPair`	Validate that a range condition carries exactly two boundaries.
Static Method	`_materializeValues`	Materialize an iterable of bound values into a tuple.
Static Method	`_normalizeOperator`	Validate and normalize a comparison operator.
Static Method	`_resolveJoinTable`	Normalize a join target into a `TableDefinition`.
Method	`_addColumnComparison`	Append a comparison between two columns of the query.
Method	`_addExists`	Append an `EXISTS` or `NOT EXISTS` condition.
Method	`_addJoin`	Append a join expression built from either calling convention.
Method	`_addMembership`	Append a set-membership condition backed by values or a subquery.
Method	`_addRaw`	Append a raw SQL condition to a clause list.
Method	`_addTyped`	Append a single-column condition of the given kind.
Method	`_addWhere`	Parse and append a condition to a clause list.
Async Method	`_aggregate`	Execute an aggregate projection over the current plan.
Method	`_nestedClauses`	Run a grouping callback and collect the conditions it declared.
Method	`_newQuery`	Create a sibling builder used for nested groups and subqueries.
Method	`_paginator`	Wrap a page of results together with its pagination metadata.
Method	`_resolvePlan`	Normalize a subquery argument into a select plan.
Method	`_shallowCopy`	Build a twin of this builder still sharing its plan.
Method	`addSelect`	Append columns to the current projection.
Method	`adoptConnection`	Bind the builder to a named connection.
Method	`adoptPlan`	Replace the plan this builder assembles.
Async Method	`avg`	Return the average value of a column among matching rows.
Async Method	`count`	Count the rows matched by the query.
Method	`crossJoin`	Add a CROSS JOIN to the query.
Method	`distinct`	Collapse duplicate rows from the query results.
Async Method	`doesntExist`	Report whether the query matches no rows.
Async Method	`exists`	Report whether the query matches at least one row.
Method	`forPage`	Limit the query to a single page of results.
Method	`fullJoin`	Add a FULL OUTER JOIN to the query.
Method	`groupBy`	Add grouping columns to the query.
Method	`having`	Add a post-grouping condition to the query.
Method	`havingRaw`	Add a raw SQL post-grouping condition.
Async Method	`insert`	Insert one or many rows into the target table.
Method	`join`	Add an INNER JOIN to the query.
Method	`joinSub`	Join a subquery as a derived table with an INNER JOIN.
Method	`latest`	Order the query by a timestamp column in descending order.
Method	`leftJoin`	Add a LEFT OUTER JOIN to the query.
Method	`leftJoinSub`	Join a subquery as a derived table with a LEFT OUTER JOIN.
Method	`limit`	Limit the number of rows returned by the query.
Method	`lockForUpdate`	Lock the selected rows against concurrent writes.
Async Method	`max`	Return the maximum value of a column among matching rows.
Async Method	`min`	Return the minimum value of a column among matching rows.
Method	`offset`	Skip the given number of rows before returning results.
Method	`oldest`	Order the query by a timestamp column in ascending order.
Method	`orderBy`	Add an ordering rule to the query.
Method	`orHaving`	Add an OR-combined post-grouping condition to the query.
Method	`orWhere`	Add an OR-combined filtering condition.
Method	`orWhereColumn`	Add an OR-combined comparison between two columns.
Method	`orWhereExists`	Add an OR-combined `EXISTS` condition.
Method	`orWhereIn`	Add an OR-combined set-membership condition.
Method	`orWhereNotExists`	Add an OR-combined `NOT EXISTS` condition.
Method	`orWhereNotIn`	Add an OR-combined set-exclusion condition.
Method	`orWhereNotNull`	Add an OR-combined `IS NOT NULL` condition.
Method	`orWhereNull`	Add an OR-combined `IS NULL` condition.
Method	`orWhereRaw`	Add an OR-combined raw SQL condition.
Method	`rightJoin`	Add a RIGHT OUTER JOIN to the query.
Method	`rightJoinSub`	Join a subquery as a derived table with a RIGHT OUTER JOIN.
Method	`select`	Restrict the query projection to the given columns.
Method	`selectRaw`	Append a raw SQL fragment to the projection.
Method	`selectSub`	Append a scalar subquery to the projection under an alias.
Method	`sharedLock`	Lock the selected rows in shared mode.
Method	`skip`	Skip the given number of rows; alias of `offset`.
Async Method	`sum`	Return the sum of a column among matching rows.
Method	`take`	Limit the number of rows returned; alias of `limit`.
Method	`toPlan`	Return the engine-agnostic plan assembled so far.
Method	`union`	Append another query's rows, collapsing duplicates.
Method	`unionAll`	Append another query's rows, keeping duplicates.
Async Method	`update`	Mass update the rows matched by the query.
Method	`where`	Add an AND-combined filtering condition.
Method	`whereBetween`	Filter rows whose column value lies between two boundaries.
Method	`whereColumn`	Compare two columns of the query against each other.
Method	`whereContains`	Filter rows whose column value contains the given text.
Method	`whereEndsWith`	Filter rows whose column value ends with the given text.
Method	`whereExists`	Keep rows for which a correlated subquery returns any row.
Method	`whereILike`	Filter rows matching a case-insensitive SQL LIKE pattern.
Method	`whereIn`	Filter rows whose column value belongs to the given set.
Method	`whereLike`	Filter rows whose column value matches an SQL LIKE pattern.
Method	`whereNotBetween`	Filter rows whose column value lies outside two boundaries.
Method	`whereNotExists`	Keep rows for which a correlated subquery returns no row.
Method	`whereNotILike`	Filter rows not matching a case-insensitive SQL LIKE pattern.
Method	`whereNotIn`	Filter rows whose column value is outside the given set.
Method	`whereNotLike`	Filter rows whose column value does not match an SQL LIKE pattern.
Method	`whereNotNull`	Filter rows whose column value is not `NULL`.
Method	`whereNull`	Filter rows whose column value is `NULL`.
Method	`whereRaw`	Add an AND-combined raw SQL condition.
Method	`whereRegexpMatch`	Filter rows whose column value matches a regular expression.
Method	`whereStartsWith`	Filter rows whose column value starts with the given text.
Instance Variable	`_plan`	Undocumented

@classmethod

def noConstraints(cls, callback: Callable[[], Relation[Any]]) -> Relation[Any]: (source) ¶

Build a relationship instance without its single-parent constraint.

Used by eager loading to read a relationship's metadata (related model, foreign key, ...) from a sample instance without binding the query to that specific instance. The setting is isolated to the current execution context, including across worker threads.

Parameters
callback:`Callable`	Zero-argument callable constructing the relationship, typically a bound relationship method such as `model.posts`.

Returns
`Relation`	The relationship built by `callback`, unconstrained.

def __await__(self) -> Generator[Any, None, Any]: (source) ¶

Allow await directly on a relationship without a terminal.

Equivalent to await relation.getResults(), mirroring how Eloquent resolves $model->relation as a property access.

Returns
`Generator`	Delegate generator driving `getResults`.

def __init__(self, parent: Model, related: type[TRelated]): (source) ¶

overrides orionis.orm.query.ModelQueryBuilder.__init__

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Bind a relationship query builder to its parent instance.

Parameters
parent:`Model`	Model instance the relationship is accessed from.
related:`type of Model`	Model class the relationship targets.

Returns
`None`	This method does not return a value.

def addConstraints(self): (source) ¶

overrides orionis.orm.contracts.relation.IRelation.addConstraints

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Constrain the query to the bound parent instance.

Returns
`None`	This method does not return a value.

def addEagerConstraints(self, models: list[Model]): (source) ¶

overrides orionis.orm.contracts.relation.IRelation.addEagerConstraints

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Constrain the query to every parent instance of an eager batch.

Parameters
models:`list of Model`	Parent instances being eager loaded together.

Returns
`None`	This method does not return a value.

async def getEager(self) -> Collection: (source) ¶

overrides orionis.orm.contracts.relation.IRelation.getEager

Execute the relationship query assembled for eager loading.

The default implementation reuses the regular get() terminal, since most relationships project every matching row the same way whether they are lazy or eager loaded.

Returns
`Collection`	Every related row across the whole eager-loaded batch.

async def getResults(self) -> Any: (source) ¶

overrides orionis.orm.contracts.relation.IRelation.getResults

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasManyRelation, orionis.orm.relations.HasOneRelation

Execute the relationship query for its bound parent instance.

Returns
`Any`	A single model, `None`, or a `Collection`, depending on the relationship kind.

def match(self, models: list[Model], results: Collection, name: str): (source) ¶

overrides orionis.orm.contracts.relation.IRelation.match

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasManyRelation, orionis.orm.relations.HasOneRelation

Group eager-loaded results and attach them to their parents.

Parameters
models:`list of Model`	Parent instances being eager loaded together.
results:`Collection`	Rows produced by `getEager`.
name:`str`	Relationship name the results are stored under.

Returns
`None`	This method does not return a value.

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.orm.query.ModelQueryBuilder.__slots__

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Undocumented

_eager_keys_empty: bool = (source) ¶

overridden in orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToRelation, orionis.orm.relations.HasOneOrManyRelation

Undocumented

_parent = (source) ¶

Undocumented