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.

class documentation

Fluent query builder bound to a model class.

It adds model awareness on top of orionis.orm.query.base_builder.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 _applyModelFilters Apply registered scopes and deletion visibility to the staged plan.
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.
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__ Declare the instance attribute slots reserved by this class.
Instance Variable _connection_name Name of the configured database connection to use.
Instance Variable _eager_loads Relations scheduled for eager loading with the query result.
Instance Variable _meta Meta supplied through meta.
Instance Variable _model Model class the queries run against.
Instance Variable _plan Plan produced by SelectPlan.
Instance Variable _scopes_applied Scopes applied flag used by ModelQueryBuilder.
Instance Variable _trashed_mode Trashed mode supplied through _TRASHED_EXCLUDE.
Instance Variable _without_scopes Without scopes produced by set.

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 orionis.orm.schema.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 _bindConnectionManager Retain the gateway owner and an optional exact migration connection.
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 chunks Read bounded result batches without changing the materializing get API.
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.
Async Method sum Return the sum of a column among matching rows.
Method take Limit the number of rows returned.
Method toPlan Return the engine-agnostic plan assembled so far.
Method toSql Render the current SELECT query without executing or mutating it.
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 _connection_manager Gateway manager retained independently of the process-wide resolver.
Instance Variable _resolved_connection Exact migration checkout retained until explicitly retargeted.
def __getattr__(self, name: str) -> Any: (source)

Expose the local scopes declared by the bound model.

Parameters
name:strAttribute requested on the builder.
Returns
typing.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)

Initialize the builder for a model class.

Parameters
model:type of orionis.orm.ModelModel class the queries run against.
Returns
NoneNo return value.
def _applyModelFilters(self): (source)

Apply registered scopes and deletion visibility to the staged plan.

Returns
NoneNo return value.
def _beforeExecute(self): (source)

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
NoneNo return value.
def _connection(self) -> IConnection: (source)

Resolve the database connection for the bound model.

Returns
orionis.database.contracts.IConnectionConnection declared by the model, or the default one.
def _defaultTimestampColumn(self) -> str: (source)

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 orionis.orm.ModelHydrated models to attach the relationships onto.
Returns
NoneNo return value.
Raises
orionis.orm.exceptions.RelationNotFoundExceptionIf a requested name is not a relationship method.
def _existsColumns(self) -> tuple[str, ...]: (source)

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 orionis.orm.ModelModels hydrated by the terminal that just ran.
Returns
NoneNo return value.
def _prepareUpdate(self, values: dict[str, Any]) -> dict[str, Any]: (source)

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)

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)

Return an independent copy of this builder.

Returns
orionis.orm.query.ModelQueryBuilderDetached copy carrying its own plan and eager-load list.
async def delete(self) -> int: (source)

Delete the matched rows, honoring soft deletes when enabled.

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

Retrieve a model by its primary key.

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

Retrieve a model by primary key or raise when absent.

Parameters
key:typing.AnyPrimary key value to look up.
Returns
orionis.orm.ModelMatching model.
Raises
orionis.orm.exceptions.ModelNotFoundExceptionIf no record matches the key.
async def first(self) -> TModel | None: (source)

Execute the query and hydrate only the first matching row.

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

Return the first matching row or raise when none exists.

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

Delete the matched rows permanently, ignoring soft deletes.

Returns
intNumber of affected rows.
async def get(self) -> Collection: (source)

Execute the query and hydrate every matching row.

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

Eager load the given relationships.

Alias of orionis.orm.query.ModelQueryBuilder.withRelations.

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

Restrict the query to soft deleted rows.

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

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
orionis.orm.collections.PaginatorPage of hydrated models with pagination metadata.
Raises
orionis.orm.exceptions.InvalidQueryExceptionIf the page or page size are not positive integers.
async def pluck(self, column: str) -> Collection: (source)

Return one column of every matching row.

Parameters
column:strColumn whose values are collected.
Returns
collections.abc.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:typing.AnyPositional arguments forwarded to the scope.
**kwargs:typing.AnyKeyword arguments forwarded to the scope.
Returns
orionis.orm.query.ModelQueryBuilderThe same builder, enabling fluent chaining.
Raises
orionis.orm.exceptions.ScopeNotFoundExceptionIf the model declares no such scope.
async def value(self, column: str) -> Any: (source)

Return a single column value of the first matching row.

Parameters
column:strColumn whose value is returned.
Returns
typing.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
orionis.orm.query.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
orionis.orm.query.ModelQueryBuilderThe same builder, enabling fluent chaining.
def withoutTrashed(self) -> Self: (source)

Exclude soft deleted rows; the default behavior.

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

Eager load the given relationships alongside the query.

Each relationship is loaded once in declaration order; orionis.orm.query.ModelQueryBuilder.load is an alias.

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

Include soft deleted rows in the query results.

Returns
orionis.orm.query.ModelQueryBuilderThe same builder, enabling fluent chaining.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_connection_name = (source)

Name of the configured database connection to use.

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

Relations scheduled for eager loading with the query result.

Meta supplied through meta.

Model class the queries run against.

_scopes_applied: bool = (source)

Scopes applied flag used by ModelQueryBuilder.

_trashed_mode: str = (source)

Trashed mode supplied through _TRASHED_EXCLUDE.

_without_scopes: set[str] = (source)

Without scopes produced by set.