orionis.orm.query.base_builder.QueryBuilderBase

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

Known subclasses: orionis.orm.query.ModelQueryBuilder, orionis.orm.query.raw_builder.RawQueryBuilder

Constructor: QueryBuilderBase(table)

View In Hierarchy

Engine shared by every Orionis query builder.

It owns the mutable SelectPlan and the whole fluent clause surface (projection, conditions, joins, grouping, ordering, paging, locking, unions) plus the terminals that do not depend on how rows are represented. Model-bound and model-less builders both derive from it, so DB.table(...) and Model.query() share one single implementation of the query language and one single SQL pipeline.

Subclasses only provide how the query reaches the database (_connection), how rows are represented (get/first), and how values are serialized before being written.

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	`__init__`	Initialize the builder with a plan for the supplied table.
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	`_beforeExecute`	Finalize the plan right before a terminal runs it.
Method	`_connection`	Resolve the database connection this builder runs against.
Method	`_defaultTimestampColumn`	Return the column `latest` and `oldest` default to.
Method	`_existsColumns`	Return the projection used by existence probes.
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	`_prepareUpdate`	Adjust an update payload before it is serialized.
Method	`_resolvePlan`	Normalize a subquery argument into a select plan.
Method	`_serializeValues`	Prepare a value mapping for storage.
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.
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 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.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_connection_name`	Undocumented
Instance Variable	`_plan`	Undocumented

@staticmethod

def _boundaryPair(bounds: Iterable[Any]) -> tuple[Any, ...]: (source) ¶

Validate that a range condition carries exactly two boundaries.

Parameters
bounds:`Iterable`	Boundary values supplied by the caller.

Returns
`tuple`	The two boundary values.

Raises
`InvalidQueryException`	If the boundaries are not exactly two values.

@staticmethod

def _materializeValues(values: Iterable[Any]) -> tuple[Any, ...]: (source) ¶

Materialize an iterable of bound values into a tuple.

Parameters
values:`Iterable`	Values to materialize; collections are unwrapped.

Returns
`tuple`	Materialized values.

@staticmethod

def _normalizeOperator(operator: Any) -> str: (source) ¶

Validate and normalize a comparison operator.

Parameters
operator:`Any`	Operator supplied by the caller.

Returns
`str`	Lowercase, trimmed operator.

Raises
`InvalidQueryException`	If the operator is not supported.

@staticmethod

def _resolveJoinTable(table: str | TableDefinition) -> TableDefinition: (source) ¶

Normalize a join target into a TableDefinition.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition.

Returns
`TableDefinition`	A schemaless definition for a bare name, or `table` as is.

def __init__(self, table: TableDefinition | None = None): (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Initialize the builder with a plan for the supplied table.

Parameters
table:`TableDefinition or None, optional`	Query target, or an empty definition until a table is selected.

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

def _addColumnComparison(self, first: str, operator: str, second: str, boolean: str) -> Self: (source) ¶

Append a comparison between two columns of the query.

Parameters
first:`str`	Left-hand column reference.
operator:`str`	Comparison operator relating both sides.
second:`str`	Right-hand column reference.
boolean:`str`	Logical connector with the previous clause.

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

Raises
`InvalidQueryException`	If the operator is not supported.

def _addExists(self, query: Any, where_type: WhereType, boolean: str) -> Self: (source) ¶

Append an EXISTS or NOT EXISTS condition.

Parameters
query:`Any`	Subquery source accepted by `_resolvePlan`.
where_type:`WhereType`	`EXISTS` or `NOT_EXISTS`.
boolean:`str`	Logical connector with the previous clause.

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

Append a join expression built from either calling convention.

Parameters
join_type:`JoinType`	Kind of join to perform.
table:`str or TableDefinition or SelectPlan`	Joined source.
on:`tuple`	The `(first, operator, second)` ON condition, where `first` may instead be a callable receiving a `JoinClause` to declare several conditions.
alias:`str or None`	Alias the joined source is referred to by.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def _addMembership(self, column: str, values: Any, where_type: WhereType, boolean: str) -> Self: (source) ¶

Append a set-membership condition backed by values or a subquery.

Parameters
column:`str`	Column name to filter by.
values:`Any`	Bound values, or a subquery producing them.
where_type:`WhereType`	`IN` or `NOT_IN`.
boolean:`str`	Logical connector with the previous clause.

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

def _addRaw(self, target: list[WhereClause], sql: str, bindings: dict[str, Any] | None, boolean: str) -> Self: (source) ¶

Append a raw SQL condition to a clause list.

Parameters
target:`list of WhereClause`	Clause list receiving the condition.
sql:`str`	SQL fragment using named `:param` placeholders.
bindings:`dict or None`	Values bound to the placeholders of the fragment.
boolean:`str`	Logical connector with the previous clause.

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

def _addTyped(self, column: str, where_type: WhereType, value: Any, boolean: str) -> Self: (source) ¶

Append a single-column condition of the given kind.

Parameters
column:`str`	Column name to filter by.
where_type:`WhereType`	Kind of condition to append.
value:`Any`	Bound value carried by the condition.
boolean:`str`	Logical connector with the previous clause.

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

def _addWhere(self, target: list[WhereClause], column: Any, args: tuple[Any, ...], boolean: str): (source) ¶

Parse and append a condition to a clause list.

Supports the grouping form (a callable receiving a nested builder), the mapping form, (column, value), and (column, operator, value).

Parameters
target:`list of WhereClause`	Clause list receiving the condition.
column:`Any`	Column name, mapping of equality pairs, or grouping callable.
args:`tuple`	Either the bound value, or an operator followed by a value.
boolean:`str`	Logical connector with the previous clause.

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

Raises
`InvalidQueryException`	If the arguments do not match a supported form.

async def _aggregate(self, function: AggregateFunction, column: str) -> Any: (source) ¶

overridden in orionis.orm.relations.BelongsToManyRelation

Execute an aggregate projection over the current plan.

Parameters
function:`AggregateFunction`	Aggregate function to apply.
column:`str`	Target column, or `"*"` for `COUNT`.

Returns
`Any`	Aggregate scalar value.

def _beforeExecute(self): (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Finalize the plan right before a terminal runs it.

Every terminal calls this hook, which is where model-aware builders inject the constraints that must apply to the query no matter how it was assembled, such as global scopes.

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

def _connection(self) -> IConnection: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder, orionis.orm.query.raw_builder.RawQueryBuilder

Resolve the database connection this builder runs against.

Returns
`IConnection`	Connection used to execute the compiled statements.

Raises
`NotImplementedError`	If the concrete builder does not resolve a connection.

def _defaultTimestampColumn(self) -> str: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return the column latest and oldest default to.

Returns
`str`	Timestamp column name.

def _existsColumns(self) -> tuple[str, ...]: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return the projection used by existence probes.

Returns
`tuple of str`	Column names to project, empty to keep the whole row.

def _nestedClauses(self, callback: Callable[[Any], Any]) -> list[WhereClause]: (source) ¶

Run a grouping callback and collect the conditions it declared.

Parameters
callback:`Callable`	Callable receiving a nested builder bound to the same table.

Returns
`list of WhereClause`	Conditions declared inside the group, in declaration order.

def _newQuery(self) -> QueryBuilderBase: (source) ¶

Create a sibling builder used for nested groups and subqueries.

Returns
`QueryBuilderBase`	Fresh builder targeting the same table and connection.

def _paginator(self, items: Collection, total: int, page: int, size: int) -> Paginator: (source) ¶

Wrap a page of results together with its pagination metadata.

Parameters
items:`Collection`	Rows of the requested page.
total:`int`	Total number of rows matched by the query.
page:`int`	Page number starting at 1.
size:`int`	Number of items per page.

Returns
`Paginator`	Length-aware page of results.

def _prepareUpdate(self, values: dict[str, Any]) -> dict[str, Any]: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Adjust an update payload before it is serialized.

Parameters
values:`dict`	Column values to assign.

Returns
`dict`	Possibly augmented payload.

def _resolvePlan(self, query: Any) -> SelectPlan: (source) ¶

Normalize a subquery argument into a select plan.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder exposing `toPlan()`, or a ready-made select plan.

Returns
`SelectPlan`	Plan describing the subquery.

Raises
`InvalidQueryException`	If the argument is not a supported subquery source.

def _serializeValues(self, values: dict[str, Any]) -> dict[str, Any]: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Prepare a value mapping for storage.

Parameters
values:`dict`	Column values to write.

Returns
`dict`	Values ready to be bound by the driver.

def _shallowCopy(self) -> Self: (source) ¶

Build a twin of this builder still sharing its plan.

Returns
`QueryBuilderBase`	Instance of the same class carrying the same bound state, including the slots declared by subclasses.

def addSelect(self, *columns: str) -> Self: (source) ¶

Append columns to the current projection.

Parameters
*columns:`str`	Column names to add to the projection.

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

def adoptConnection(self, name: str | None) -> Self: (source) ¶

Bind the builder to a named connection.

Parameters
name:`str or None`	Named connection, or `None` for the default one.

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

def adoptPlan(self, plan: SelectPlan) -> Self: (source) ¶

Replace the plan this builder assembles.

Parameters
plan:`SelectPlan`	Plan the builder continues refining.

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

async def avg(self, column: str) -> float | None: (source) ¶

Return the average value of a column among matching rows.

Parameters
column:`str`	Column to aggregate.

Returns
`float or None`	Average value, or `None` without matches.

def clone(self) -> Self: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Return an independent copy of this builder.

The copy carries a detached plan, so refining it never mutates the query it was branched from.

Returns
`QueryBuilderBase`	Detached copy sharing the same target and connection.

async def count(self, column: str = '*') -> int: (source) ¶

Count the rows matched by the query.

Parameters
column:`str, optional`	Column to count; `"*"` counts every matching row.

Returns
`int`	Number of matching rows.

def crossJoin(self, table: str | TableDefinition, *, alias: str | None = None) -> Self: (source) ¶

Add a CROSS JOIN to the query.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition.
alias:`str or None, optional`	Alias the joined table is referred to by inside the query.

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

async def delete(self) -> int: (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Delete the rows matched by the query.

Returns
`int`	Number of affected rows.

def distinct(self) -> Self: (source) ¶

Collapse duplicate rows from the query results.

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

async def doesntExist(self) -> bool: (source) ¶

Report whether the query matches no rows.

Returns
`bool`	`True` when no matching row exists.

async def exists(self) -> bool: (source) ¶

overridden in orionis.orm.relations.BelongsToManyRelation

Report whether the query matches at least one row.

Returns
`bool`	`True` when a matching row exists.

def forPage(self, page: int, per_page: int = _DEFAULT_PER_PAGE) -> Self: (source) ¶

Limit the query to a single page of results.

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

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

Raises
`InvalidQueryException`	If the page or page size are not positive integers.

def fullJoin(self, table: str | TableDefinition, first: Any = None, operator: str | None = None, second: str | None = None, *, alias: str | None = None) -> Self: (source) ¶

Add a FULL OUTER JOIN to the query.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.
alias:`str or None, optional`	Alias the joined table is referred to by inside the query.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def groupBy(self, *columns: str) -> Self: (source) ¶

Add grouping columns to the query.

Parameters
*columns:`str`	Columns to group by.

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

def having(self, column: Any, *args: Any) -> Self: (source) ¶

Add a post-grouping condition to the query.

Parameters
column:`Any`	Column name, mapping of equality pairs, or grouping callable.
*args:`Any`	Either the bound value, or an operator followed by a value.

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

Raises
`InvalidQueryException`	If the arguments do not match a supported form.

def havingRaw(self, sql: str, bindings: dict[str, Any] | None = None) -> Self: (source) ¶

Add a raw SQL post-grouping condition.

Parameters
sql:`str`	SQL fragment using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the fragment.

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

async def insert(self, values: dict[str, Any] | list[dict[str, Any]]) -> InsertResult: (source) ¶

Insert one or many rows into the target table.

Parameters
values:`dict or list of dict`	Column values for one row, or a list of rows.

Returns
`InsertResult`	Result carrying the generated key and affected row count.

Raises
`InvalidQueryException`	If no values are provided.

def join(self, table: str | TableDefinition, first: Any = None, operator: str | None = None, second: str | None = None, *, alias: str | None = None) -> Self: (source) ¶

Add an INNER JOIN to the query.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition when it declares a real schema (for instance `Model.__meta__.table`).
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause` to declare several ones.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.
alias:`str or None, optional`	Alias the joined table is referred to by inside the query.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def joinSub(self, query: Any, alias: str, first: Any = None, operator: str | None = None, second: str | None = None) -> Self: (source) ¶

Join a subquery as a derived table with an INNER JOIN.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.
alias:`str`	Name the derived table is referred to by.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def latest(self, column: str | None = None) -> Self: (source) ¶

Order the query by a timestamp column in descending order.

Parameters
column:`str or None, optional`	Column to sort by; defaults to the creation timestamp.

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

def leftJoin(self, table: str | TableDefinition, first: Any = None, operator: str | None = None, second: str | None = None, *, alias: str | None = None) -> Self: (source) ¶

Add a LEFT OUTER JOIN to the query.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.
alias:`str or None, optional`	Alias the joined table is referred to by inside the query.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def leftJoinSub(self, query: Any, alias: str, first: Any = None, operator: str | None = None, second: str | None = None) -> Self: (source) ¶

Join a subquery as a derived table with a LEFT OUTER JOIN.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.
alias:`str`	Name the derived table is referred to by.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def limit(self, value: int) -> Self: (source) ¶

Limit the number of rows returned by the query.

Parameters
value:`int`	Maximum number of rows, must not be negative.

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

Raises
`InvalidQueryException`	If the value is negative.

def lockForUpdate(self) -> Self: (source) ¶

Lock the selected rows against concurrent writes.

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

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

Return the maximum value of a column among matching rows.

Parameters
column:`str`	Column to aggregate.

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

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

Return the minimum value of a column among matching rows.

Parameters
column:`str`	Column to aggregate.

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

def offset(self, value: int) -> Self: (source) ¶

Skip the given number of rows before returning results.

Parameters
value:`int`	Number of rows to skip, must not be negative.

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

Raises
`InvalidQueryException`	If the value is negative.

def oldest(self, column: str | None = None) -> Self: (source) ¶

Order the query by a timestamp column in ascending order.

Parameters
column:`str or None, optional`	Column to sort by; defaults to the creation timestamp.

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

def orderBy(self, column: str, direction: str = 'asc') -> Self: (source) ¶

Add an ordering rule to the query.

Parameters
column:`str`	Column to sort by.
direction:`str, optional`	`"asc"` or `"desc"`. Defaults to ascending.

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

Raises
`InvalidQueryException`	If the direction is not `"asc"` or `"desc"`.

def orHaving(self, column: Any, *args: Any) -> Self: (source) ¶

Add an OR-combined post-grouping condition to the query.

Parameters
column:`Any`	Column name, mapping of equality pairs, or grouping callable.
*args:`Any`	Either the bound value, or an operator followed by a value.

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

Raises
`InvalidQueryException`	If the arguments do not match a supported form.

def orWhere(self, column: Any, *args: Any) -> Self: (source) ¶

Add an OR-combined filtering condition.

Parameters
column:`Any`	Column name, mapping of equality pairs, or grouping callable.
*args:`Any`	Either the bound value, or an operator followed by a value.

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

Raises
`InvalidQueryException`	If the arguments do not match a supported form.

def orWhereColumn(self, first: str, operator: str, second: str) -> Self: (source) ¶

Add an OR-combined comparison between two columns.

Parameters
first:`str`	Left-hand column reference, optionally qualified.
operator:`str`	Comparison operator relating both sides.
second:`str`	Right-hand column reference, optionally qualified.

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

Raises
`InvalidQueryException`	If the operator is not supported.

def orWhereExists(self, query: Any) -> Self: (source) ¶

Add an OR-combined EXISTS condition.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

def orWhereIn(self, column: str, values: Any) -> Self: (source) ¶

Add an OR-combined set-membership condition.

Parameters
column:`str`	Column name to filter by.
values:`Any`	Accepted values, or a subquery producing them.

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

def orWhereNotExists(self, query: Any) -> Self: (source) ¶

Add an OR-combined NOT EXISTS condition.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

def orWhereNotIn(self, column: str, values: Any) -> Self: (source) ¶

Add an OR-combined set-exclusion condition.

Parameters
column:`str`	Column name to filter by.
values:`Any`	Rejected values, or a subquery producing them.

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

def orWhereNotNull(self, column: str) -> Self: (source) ¶

Add an OR-combined IS NOT NULL condition.

Parameters
column:`str`	Column name to filter by.

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

def orWhereNull(self, column: str) -> Self: (source) ¶

Add an OR-combined IS NULL condition.

Parameters
column:`str`	Column name to filter by.

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

def orWhereRaw(self, sql: str, bindings: dict[str, Any] | None = None) -> Self: (source) ¶

Add an OR-combined raw SQL condition.

Parameters
sql:`str`	SQL fragment using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the fragment.

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

def rightJoin(self, table: str | TableDefinition, first: Any = None, operator: str | None = None, second: str | None = None, *, alias: str | None = None) -> Self: (source) ¶

Add a RIGHT OUTER JOIN to the query.

Parameters
table:`str or TableDefinition`	Table name to join, or its full definition.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.
alias:`str or None, optional`	Alias the joined table is referred to by inside the query.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def rightJoinSub(self, query: Any, alias: str, first: Any = None, operator: str | None = None, second: str | None = None) -> Self: (source) ¶

Join a subquery as a derived table with a RIGHT OUTER JOIN.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.
alias:`str`	Name the derived table is referred to by.
first:`Any, optional`	Left-hand column of the ON condition, or a callable receiving a `JoinClause`.
operator:`str or None, optional`	Comparison operator relating both sides.
second:`str or None, optional`	Right-hand column of the ON condition.

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

Raises
`InvalidQueryException`	If the ON condition is incomplete.

def select(self, *columns: str) -> Self: (source) ¶

Restrict the query projection to the given columns.

Parameters
*columns:`str`	Column names to project; empty selects every column.

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

def selectRaw(self, sql: str, bindings: dict[str, Any] | None = None, alias: str | None = None) -> Self: (source) ¶

Append a raw SQL fragment to the projection.

Parameters
sql:`str`	SQL fragment using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the fragment.
alias:`str or None, optional`	Name the fragment is projected under; required for the value to be addressable when the query is joined as a derived table.

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

def selectSub(self, query: Any, alias: str) -> Self: (source) ¶

Append a scalar subquery to the projection under an alias.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.
alias:`str`	Name the projected value is exposed under.

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

def sharedLock(self) -> Self: (source) ¶

Lock the selected rows in shared mode.

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

def skip(self, value: int) -> Self: (source) ¶

Skip the given number of rows; alias of offset.

Parameters
value:`int`	Number of rows to skip, must not be negative.

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

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

Return the sum of a column among matching rows.

Parameters
column:`str`	Column to aggregate.

Returns
`Any`	Sum of the values, or `0` without matches.

def take(self, value: int) -> Self: (source) ¶

Limit the number of rows returned; alias of limit.

Parameters
value:`int`	Maximum number of rows, must not be negative.

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

def toPlan(self) -> SelectPlan: (source) ¶

Return the engine-agnostic plan assembled so far.

The plan is the only contract between the fluent API and the SQL compiler; exposing it lets a builder be embedded as a subquery of another one.

Returns
`SelectPlan`	Live plan owned by this builder.

def union(self, query: Any) -> Self: (source) ¶

Append another query's rows, collapsing duplicates.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

def unionAll(self, query: Any) -> Self: (source) ¶

Append another query's rows, keeping duplicates.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

async def update(self, values: dict[str, Any]) -> int: (source) ¶

overridden in orionis.orm.relations.BelongsToManyRelation

Mass update the rows matched by the query.

Parameters
values:`dict`	Column values to assign.

Returns
`int`	Number of affected rows.

Raises
`InvalidQueryException`	If no values are provided.

def where(self, column: Any, *args: Any) -> Self: (source) ¶

Add an AND-combined filtering condition.

Accepts where("col", value), where("col", op, value), a mapping of equality conditions, or a callable receiving a nested builder whose conditions are grouped in parentheses.

Parameters
column:`Any`	Column name, mapping of equality pairs, or grouping callable.
*args:`Any`	Either the bound value, or an operator followed by a value.

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

Raises
`InvalidQueryException`	If the arguments do not match a supported form.

def whereBetween(self, column: str, bounds: Iterable[Any]) -> Self: (source) ¶

Filter rows whose column value lies between two boundaries.

Parameters
column:`str`	Column name to filter by.
bounds:`Iterable`	Exactly two values: the lower and upper boundaries.

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

Raises
`InvalidQueryException`	If the boundaries are not exactly two values.

def whereColumn(self, first: str, operator: str, second: str) -> Self: (source) ¶

Compare two columns of the query against each other.

Parameters
first:`str`	Left-hand column reference, optionally qualified.
operator:`str`	Comparison operator relating both sides.
second:`str`	Right-hand column reference, optionally qualified.

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

Raises
`InvalidQueryException`	If the operator is not supported.

def whereContains(self, column: str, value: str) -> Self: (source) ¶

Filter rows whose column value contains the given text.

Parameters
column:`str`	Column name to filter by.
value:`str`	Literal substring to match.

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

def whereEndsWith(self, column: str, value: str) -> Self: (source) ¶

Filter rows whose column value ends with the given text.

Parameters
column:`str`	Column name to filter by.
value:`str`	Literal suffix to match.

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

def whereExists(self, query: Any) -> Self: (source) ¶

Keep rows for which a correlated subquery returns any row.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

def whereILike(self, column: str, pattern: str) -> Self: (source) ¶

Filter rows matching a case-insensitive SQL LIKE pattern.

Parameters
column:`str`	Column name to filter by.
pattern:`str`	SQL LIKE pattern, using `%` and `_` wildcards.

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

def whereIn(self, column: str, values: Any) -> Self: (source) ¶

Filter rows whose column value belongs to the given set.

Parameters
column:`str`	Column name to filter by.
values:`Any`	Accepted values, or a subquery producing them.

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

def whereLike(self, column: str, pattern: str) -> Self: (source) ¶

Filter rows whose column value matches an SQL LIKE pattern.

Parameters
column:`str`	Column name to filter by.
pattern:`str`	SQL LIKE pattern, using `%` and `_` wildcards.

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

def whereNotBetween(self, column: str, bounds: Iterable[Any]) -> Self: (source) ¶

Filter rows whose column value lies outside two boundaries.

Parameters
column:`str`	Column name to filter by.
bounds:`Iterable`	Exactly two values: the lower and upper boundaries.

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

Raises
`InvalidQueryException`	If the boundaries are not exactly two values.

def whereNotExists(self, query: Any) -> Self: (source) ¶

Keep rows for which a correlated subquery returns no row.

Parameters
query:`Any`	Callable receiving a fresh builder, another builder, or a ready-made select plan.

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

def whereNotILike(self, column: str, pattern: str) -> Self: (source) ¶

Filter rows not matching a case-insensitive SQL LIKE pattern.

Parameters
column:`str`	Column name to filter by.
pattern:`str`	SQL LIKE pattern, using `%` and `_` wildcards.

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

def whereNotIn(self, column: str, values: Any) -> Self: (source) ¶

Filter rows whose column value is outside the given set.

Parameters
column:`str`	Column name to filter by.
values:`Any`	Rejected values, or a subquery producing them.

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

def whereNotLike(self, column: str, pattern: str) -> Self: (source) ¶

Filter rows whose column value does not match an SQL LIKE pattern.

Parameters
column:`str`	Column name to filter by.
pattern:`str`	SQL LIKE pattern, using `%` and `_` wildcards.

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

def whereNotNull(self, column: str) -> Self: (source) ¶

Filter rows whose column value is not NULL.

Parameters
column:`str`	Column name to filter by.

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

def whereNull(self, column: str) -> Self: (source) ¶

Filter rows whose column value is NULL.

Parameters
column:`str`	Column name to filter by.

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

def whereRaw(self, sql: str, bindings: dict[str, Any] | None = None) -> Self: (source) ¶

Add an AND-combined raw SQL condition.

Values must be supplied through bindings so the driver binds and escapes them; interpolating them into sql would open the query to injection.

Parameters
sql:`str`	SQL fragment using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the fragment.

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

def whereRegexpMatch(self, column: str, pattern: str) -> Self: (source) ¶

Filter rows whose column value matches a regular expression.

The exact regular expression dialect depends on the underlying database engine.

Parameters
column:`str`	Column name to filter by.
pattern:`str`	Regular expression pattern.

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

def whereStartsWith(self, column: str, value: str) -> Self: (source) ¶

Filter rows whose column value starts with the given text.

Parameters
column:`str`	Column name to filter by.
value:`str`	Literal prefix to match.

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

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

overridden in orionis.orm.query.ModelQueryBuilder, orionis.orm.query.raw_builder.RawQueryBuilder

Undocumented

_connection_name: str | None = (source) ¶

overridden in orionis.orm.query.ModelQueryBuilder

Undocumented

_plan = (source) ¶

Undocumented