orionis.orm.relations.BelongsToRelation

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 BelongsToRelation(Relation[TRelated]): (source)

Constructor: BelongsToRelation(parent, related, foreign_key, owner_key)

View In Hierarchy

Inverse relationship: the foreign key lives on the parent row.

Mirrors Eloquent's BelongsTo: for instance Post belongsTo User, where posts.user_id points back at users.id. Unlike hasOne/hasMany, the foreign key is read from the parent instance itself, never queried on the related table.

Method	`__init__`	Bind the relationship.
Method	`addConstraints`	Constrain the query to the row owning the parent's foreign key.
Method	`addEagerConstraints`	Constrain the query to the rows owning every child's foreign key.
Async Method	`getResults`	Retrieve the owning row referenced by the parent's foreign key.
Method	`match`	Attach the owning row to each child instance.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_eager_keys_empty`	Undocumented
Instance Variable	`_foreign_key`	Undocumented
Instance Variable	`_owner_key`	Undocumented

Inherited from Relation:

Class Method	`noConstraints`	Build a relationship instance without its single-parent constraint.
Method	`__await__`	Allow `await` directly on a relationship without a terminal.
Async Method	`getEager`	Execute the relationship query assembled for eager loading.
Instance Variable	`_parent`	Undocumented

Inherited from ModelQueryBuilder (via Relation):

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 Relation, 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

def __init__(self, parent: Model, related: type[TRelated], foreign_key: str | None, owner_key: str | None): (source) ¶

overrides orionis.orm.relations.Relation.__init__

Bind the relationship.

Parameters
parent:`Model`	Model instance the relationship is accessed from.
related:`type of Model`	Model class the relationship targets.
foreign_key:`str or None`	Column on the parent referencing the related row; defaults to `snake_case(RelatedClass) + "_id"`.
owner_key:`str or None`	Column on the related table identifying the owning row; defaults to the related model's primary key.

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

def addConstraints(self): (source) ¶

overrides orionis.orm.relations.Relation.addConstraints

Constrain the query to the row owning the parent's foreign key.

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

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

overrides orionis.orm.relations.Relation.addEagerConstraints

Constrain the query to the rows owning every child's foreign key.

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

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

async def getResults(self) -> TRelated | None: (source) ¶

overrides orionis.orm.relations.Relation.getResults

Retrieve the owning row referenced by the parent's foreign key.

Returns
`Model or None`	Owning model, or `None` when the foreign key is unset or references no row.

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

overrides orionis.orm.relations.Relation.match

Attach the owning row to each child instance.

Parameters
models:`list of Model`	Child instances being eager loaded together.
results:`Collection`	Owning rows produced by `getEager`.
name:`str`	Relationship name the result is stored under.

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

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

overrides orionis.orm.relations.Relation.__slots__

Undocumented

_eager_keys_empty = (source) ¶

overrides orionis.orm.relations.Relation._eager_keys_empty

Undocumented

_foreign_key = (source) ¶

Undocumented

_owner_key = (source) ¶

Undocumented