orionis.orm.query.raw_builder.RawQueryBuilder

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

Constructor: RawQueryBuilder(table)

View In Hierarchy

Fluent query builder over a plain table name.

Unlike orionis.orm.query.builder.ModelQueryBuilder, it is not bound to a Model: rows are returned as plain dictionaries and the target table carries no declared schema, so the SQL compiler declares each referenced column lazily. Built by orionis.orm.db.DB.table.

Every clause method comes from QueryBuilderBase, the same engine model queries run on, so both entry points speak exactly the same query language and compile through the same pipeline.

Method	`_assertTarget`	Ensure a table was selected before executing the query.
Method	`_connection`	Resolve the database connection this builder runs against.
Method	`connection`	Change the connection this builder runs against.
Async Method	`first`	Execute the query and return only the first matching row.
Async Method	`get`	Execute the query and return every matching row.
Async Method	`paginate`	Execute the query returning a length-aware page of results.
Async Method	`pluck`	Return one column of every matching row.
Method	`table`	Change the table this builder queries against.
Async Method	`value`	Return a single column value of the first matching row.
Class Variable	`__slots__`	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	`__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	`_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.
Instance Variable	`_connection_name`	Undocumented
Instance Variable	`_plan`	Undocumented

def _assertTarget(self): (source) ¶

Ensure a table was selected before executing the query.

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

Raises
`InvalidQueryException`	If the builder has no target table.

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

overrides orionis.orm.query.base_builder.QueryBuilderBase._connection

Resolve the database connection this builder runs against.

Returns
`IConnection`	Named connection, or the default one.

def connection(self, name: str) -> Self: (source) ¶

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.connection

Change the connection this builder runs against.

Parameters
name:`str`	Named connection to run the query against.

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

async def first(self) -> dict[str, Any] | None: (source) ¶

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.first

Execute the query and return only the first matching row.

Returns
`dict or None`	First matching row, or `None` without matches.

Raises
`InvalidQueryException`	If no table was selected.
`QueryException`	If the statement fails to compile or execute.

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

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.get

Execute the query and return every matching row.

Returns
`Collection`	Collection of plain dictionaries, one per row.

Raises
`InvalidQueryException`	If no table was selected.
`QueryException`	If the statement fails to compile or execute.

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

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.paginate

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 rows with pagination metadata.

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

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

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.pluck

Return one column of every matching row.

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

Returns
`Collection`	Collection of column values.

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

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.table

Change the table this builder queries against.

Only the target is replaced; clauses declared beforehand are preserved, so the call order never silently drops conditions.

Parameters
name:`str`	Logical table name, without the connection prefix.
alias:`str or None, optional`	Alias the table is referred to by inside the query.

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

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

overrides orionis.orm.contracts.raw_builder.IRawQueryBuilder.value

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.

__slots__: tuple = (source) ¶

overrides orionis.orm.query.base_builder.QueryBuilderBase.__slots__

Undocumented