orionis.orm.contracts.IModelQueryBuilder

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 IModelQueryBuilder(IQueryBuilderBase): (source)

Known subclasses: orionis.orm.contracts.relation.IRelation, orionis.orm.query.ModelQueryBuilder

View In Hierarchy

Contract for the query builder bound to a model class.

It inherits the whole query language from IQueryBuilderBase and only adds what model awareness brings: hydrated results, primary-key lookups, and relationship eager loading.

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	`get`	Execute the query and hydrate every matching row.
Method	`load`	Eager load the given relationships; alias of `withRelations`.
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	`value`	Return a single column value of the first matching row.
Method	`withRelations`	Eager load the given relationships alongside the query.
Class Variable	`__slots__`	Undocumented

Inherited from IQueryBuilderBase:

Method	`addSelect`	Append columns to the current projection.
Async Method	`avg`	Return the average value of a column among matching rows.
Method	`clone`	Return an independent copy of this builder.
Async Method	`count`	Count the rows matched by the query.
Method	`crossJoin`	Add a CROSS JOIN to the query.
Async Method	`delete`	Delete the rows matched by 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 LIKE pattern.
Method	`whereNotIn`	Filter rows whose column value is outside the given set.
Method	`whereNotLike`	Filter rows not matching 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.

@abstractmethod

async def find(self, key: Any) -> Model | None: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Retrieve a model by its primary key.

Parameters
key:`Any`	Primary key value to look up.

Returns
`Model or None`	Matching model, or `None` when absent.

@abstractmethod

async def findOrFail(self, key: Any) -> Model: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Retrieve a model by primary key or raise when absent.

Parameters
key:`Any`	Primary key value to look up.

Returns
`Model`	Matching model.

Raises
`ModelNotFoundException`	If no record matches the key.

@abstractmethod

async def first(self) -> Model | None: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder, orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToManyRelation

Execute the query and hydrate only the first matching row.

Returns
`Model or None`	First matching model, or `None` without matches.

@abstractmethod

async def firstOrFail(self) -> Model: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return the first matching row or raise when none exists.

Returns
`Model`	First matching model.

Raises
`ModelNotFoundException`	If the query yields no rows.

@abstractmethod

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

overridden in orionis.orm.query.ModelQueryBuilder, orionis.orm.relations.BelongsToManyRelation, orionis.orm.relations.BelongsToManyRelation

Execute the query and hydrate every matching row.

Returns
`Collection`	Collection of hydrated model instances.

@abstractmethod

def load(self, *names: str) -> Self: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Eager load the given relationships; alias of withRelations.

Parameters
*names:`str`	Relationship method names declared on the model.

Returns
`IModelQueryBuilder`	The same builder, enabling fluent chaining.

@abstractmethod

async def paginate(self, page: int = 1, per_page: int = 15) -> Paginator: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Execute the query returning a length-aware page of results.

Parameters
page:`int, optional`	Page number starting at 1. Defaults to the first page.
per_page:`int, optional`	Number of items per page. Defaults to 15.

Returns
`Paginator`	Page of hydrated models with pagination metadata.

@abstractmethod

async def pluck(self, column: str) -> Collection: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return one column of every matching row.

Parameters
column:`str`	Column whose values are collected.

Returns
`Collection`	Collection of column values.

@abstractmethod

async def value(self, column: str) -> Any: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return a single column value of the first matching row.

Parameters
column:`str`	Column whose value is returned.

Returns
`Any`	Column value, or `None` without matches.

@abstractmethod

def withRelations(self, *names: str) -> Self: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Eager load the given relationships alongside the query.

Parameters
*names:`str`	Relationship method names declared on the model.

Returns
`IModelQueryBuilder`	The same builder, enabling fluent chaining.

__slots__: tuple = (source) ¶

overrides orionis.orm.contracts.base_builder.IQueryBuilderBase.__slots__

overridden in orionis.orm.contracts.relation.IRelation, orionis.orm.query.ModelQueryBuilder

Undocumented