ORIONIS API REFERENCE

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

orionis.orm.query.ModelQueryBuilder

class documentation

class ModelQueryBuilder(QueryBuilderBase, IModelQueryBuilder): (source)

Known subclasses: orionis.orm.relations.Relation

Constructor: ModelQueryBuilder(model)

View In Hierarchy

Fluent query builder bound to a model class.

It adds model awareness on top of QueryBuilderBase: rows are hydrated into model instances, written values go through the declared casts, timestamps are maintained, and relationships can be eager loaded. The query language itself is entirely inherited, so a model query and a DB.table(...) query compile identically.

Method __getattr__ Expose the local scopes declared by the bound model.
Method __init__ Initialize the builder for a model class.
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.
Class Variable __slots__ Undocumented
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:

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 __getattr__(self, name: str) -> Any: (source)

Expose the local scopes declared by the bound model.

Parameters
name:strAttribute requested on the builder.
Returns
AnyCallable applying the scope and returning the builder.
Raises
AttributeErrorIf the name is neither a builder member nor a local scope.
def __init__(self, model: type[TModel]): (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase.__init__
overridden in orionis.orm.relations.Relation

Initialize the builder for a model class.

Parameters
model:type of ModelModel class the queries run against.
Returns
NoneThis method does not return a value.
def _beforeExecute(self): (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._beforeExecute

Apply the global scopes and the soft delete filter once.

Scopes are folded into the plan at execution time, not at construction, so withoutGlobalScope and withTrashed can be called anywhere in the chain.

Returns
NoneThis method does not return a value.
def _connection(self) -> IConnection: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._connection

Resolve the database connection for the bound model.

Returns
IConnectionConnection declared by the model, or the default one.
def _defaultTimestampColumn(self) -> str: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._defaultTimestampColumn

Return the column latest and oldest default to.

Returns
strCreation timestamp column when declared, primary key otherwise.
async def _eagerLoad(self, models: list[TModel]): (source)

Resolve every pending eager-loaded relationship for a result set.

Reads each relationship's metadata from the first model (its query is otherwise identical for every instance of the same class), constrains it to the whole batch in a single query, and assigns the grouped results back to each model.

Parameters
models:list of ModelHydrated models to attach the relationships onto.
Returns
NoneThis method does not return a value.
Raises
RelationNotFoundExceptionIf a requested name is not a relationship method.
def _existsColumns(self) -> tuple[str, ...]: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._existsColumns

Return the projection used by existence probes.

Returns
tuple of strThe primary key alone, the cheapest column to fetch.
async def _fireRetrieved(self, models: list[TModel]): (source)

Dispatch the retrieved event for freshly hydrated models.

Parameters
models:list of ModelModels hydrated by the terminal that just ran.
Returns
NoneThis method does not return a value.
def _prepareUpdate(self, values: dict[str, Any]) -> dict[str, Any]: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._prepareUpdate

Refresh the update timestamp of a mass update payload.

Parameters
values:dictColumn values to assign.
Returns
dictPayload including the refreshed update timestamp, when the model maintains timestamps.
def _relationErrorMessage(self, name: str) -> str: (source)

Build the error message for an unresolvable relationship name.

Parameters
name:strRelationship name requested for eager loading.
Returns
strHuman readable error message.
def _serializeValues(self, values: dict[str, Any]) -> dict[str, Any]: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._serializeValues

Apply the model casts before values reach the database.

Parameters
values:dictColumn values to write.
Returns
dictValues converted to their storage representation.
def clone(self) -> Self: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase.clone
overridden in orionis.orm.relations.BelongsToManyRelation

Return an independent copy of this builder.

Returns
ModelQueryBuilderDetached copy carrying its own plan and eager-load list.
async def delete(self) -> int: (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase.delete
overridden in orionis.orm.relations.BelongsToManyRelation

Delete the matched rows, honoring soft deletes when enabled.

Returns
intNumber of affected rows.
async def find(self, key: Any) -> TModel | None: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.find

Retrieve a model by its primary key.

Parameters
key:AnyPrimary key value to look up.
Returns
Model or NoneMatching model, or None when absent.
async def findOrFail(self, key: Any) -> TModel: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.findOrFail

Retrieve a model by primary key or raise when absent.

Parameters
key:AnyPrimary key value to look up.
Returns
ModelMatching model.
Raises
ModelNotFoundExceptionIf no record matches the key.
async def first(self) -> TModel | None: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.first
overridden in orionis.orm.relations.BelongsToManyRelation

Execute the query and hydrate only the first matching row.

Returns
Model or NoneFirst matching model, or None without matches.
Raises
QueryExceptionIf the statement fails to compile or execute.
RelationNotFoundExceptionIf an eager-loaded relationship name does not resolve to one.
async def firstOrFail(self) -> TModel: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.firstOrFail

Return the first matching row or raise when none exists.

Returns
ModelFirst matching model.
Raises
ModelNotFoundExceptionIf the query yields no rows.
async def forceDelete(self) -> int: (source)
overridden in orionis.orm.relations.BelongsToManyRelation

Delete the matched rows permanently, ignoring soft deletes.

Returns
intNumber of affected rows.
async def get(self) -> Collection: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.get
overridden in orionis.orm.relations.BelongsToManyRelation

Execute the query and hydrate every matching row.

Returns
CollectionCollection of hydrated model instances.
Raises
QueryExceptionIf the statement fails to compile or execute.
RelationNotFoundExceptionIf an eager-loaded relationship name does not resolve to one.
def load(self, *names: str) -> Self: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.load

Eager load the given relationships; alias of withRelations.

Parameters
*names:strRelationship method names declared on the model.
Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
def onlyTrashed(self) -> Self: (source)

Restrict the query to soft deleted rows.

Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
async def paginate(self, page: int = 1, per_page: int = _DEFAULT_PER_PAGE) -> Paginator: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.paginate

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

Parameters
page:int, optionalPage number starting at 1. Defaults to the first page.
per_page:int, optionalNumber of items per page. Defaults to 15.
Returns
PaginatorPage of hydrated models with pagination metadata.
Raises
InvalidQueryExceptionIf the page or page size are not positive integers.
async def pluck(self, column: str) -> Collection: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.pluck

Return one column of every matching row.

Parameters
column:strColumn whose values are collected.
Returns
CollectionCollection of column values.
async def restore(self) -> int: (source)

Restore every soft deleted row matched by the query.

Returns
intNumber of restored rows.
def scope(self, name: str, *args: Any, **kwargs: Any) -> Self: (source)

Apply a local scope by name.

Useful when the scope name collides with a builder method; the attribute form (query.active()) is the common one.

Parameters
name:strScope name, without the scope prefix.
*args:AnyPositional arguments forwarded to the scope.
**kwargs:AnyKeyword arguments forwarded to the scope.
Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
Raises
ScopeNotFoundExceptionIf the model declares no such scope.
async def value(self, column: str) -> Any: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.value

Return a single column value of the first matching row.

Parameters
column:strColumn whose value is returned.
Returns
AnyColumn value, or None without matches.
def withoutGlobalScope(self, name: str) -> Self: (source)

Disable one global scope for this query.

Parameters
name:strName the global scope was registered under.
Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
def withoutGlobalScopes(self, *names: str) -> Self: (source)

Disable several global scopes, or every one of them.

Parameters
*names:strScope names to disable; empty disables all of them.
Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
def withoutTrashed(self) -> Self: (source)

Exclude soft deleted rows; the default behavior.

Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
def withRelations(self, *names: str) -> Self: (source)
overrides orionis.orm.contracts.IModelQueryBuilder.withRelations

Eager load the given relationships alongside the query.

Each relationship is loaded once in declaration order; load is an alias.

Parameters
*names:strRelationship method names declared on the model.
Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
def withTrashed(self) -> Self: (source)

Include soft deleted rows in the query results.

Returns
ModelQueryBuilderThe same builder, enabling fluent chaining.
__slots__: tuple[str, ...] = (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase.__slots__
overridden in orionis.orm.relations.Relation

Undocumented

_connection_name = (source)
overrides orionis.orm.query.base_builder.QueryBuilderBase._connection_name

Undocumented

_eager_loads: dict[str, None] = (source)

Undocumented

_meta = (source)

Undocumented

_model = (source)

Undocumented

_scopes_applied: bool = (source)

Undocumented

_trashed_mode: str = (source)

Undocumented

_without_scopes: set[str] = (source)

Undocumented