orionis.orm.contracts.query_builder.IQueryBuilder

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

Known subclasses: orionis.orm.query_builder.QueryBuilder

View In Hierarchy

Contract of the entry point backing the DB facade.

Implementations resolve named connections, start model-less queries, and drive transactions. They are registered as singletons, so every method must be free of per-query state: the connection scope travels with the returned object rather than being stored on the service.

Async Method	`beginTransaction`	Begin a transaction, or a savepoint when one is already active.
Async Method	`commit`	Commit the innermost active transaction or savepoint.
Method	`connection`	Return a gateway scoped to the connection with the given name.
Async Method	`execute`	Run a raw data-modifying statement and return the affected rows.
Method	`getDefaultName`	Return the name of the default connection.
Async Method	`rollback`	Roll back the innermost active transaction or savepoint.
Async Method	`select`	Run a raw SELECT statement and return its rows.
Method	`setDefaultName`	Change the connection used when none is specified.
Async Method	`statement`	Run a raw statement without inspecting its result.
Method	`table`	Build a fluent, model-less query over a plain table name.
Method	`transaction`	Return a transaction usable as an async context manager.
Class Variable	`__slots__`	Undocumented

@abstractmethod

async def beginTransaction(self, name: str | None = None): (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Begin a transaction, or a savepoint when one is already active.

Parameters
name:`str or None, optional`	Named connection to start the transaction on, or `None` for the default connection.

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

Raises
`TransactionException`	If the transaction cannot be started.

@abstractmethod

async def commit(self, name: str | None = None): (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Commit the innermost active transaction or savepoint.

Parameters
name:`str or None, optional`	Named connection to commit, or `None` for the default connection.

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

Raises
`TransactionException`	If no transaction is active.

@abstractmethod

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

overridden in orionis.orm.query_builder.QueryBuilder

Return a gateway scoped to the connection with the given name.

Parameters
name:`str or None, optional`	Connection name as declared in the database configuration, or `None` for the default connection.

Returns
`Self`	Gateway bound to the requested connection.

Raises
`ConnectionNotFoundException`	If the connection is not declared in the configuration.

@abstractmethod

async def execute(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> int: (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Run a raw data-modifying statement and return the affected rows.

Parameters
sql:`str`	Raw SQL using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on, or `None` for the connection this gateway is scoped to.

Returns
`int`	Number of affected rows.

Raises
`QueryException`	If the statement fails to execute.

@abstractmethod

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

overridden in orionis.orm.query_builder.QueryBuilder

Return the name of the default connection.

Returns
`str`	Name of the connection used when none is specified.

@abstractmethod

async def rollback(self, name: str | None = None): (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Roll back the innermost active transaction or savepoint.

Parameters
name:`str or None, optional`	Named connection to roll back, or `None` for the default connection.

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

Raises
`TransactionException`	If no transaction is active.

@abstractmethod

async def select(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> list[dict[str, object]]: (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Run a raw SELECT statement and return its rows.

Parameters
sql:`str`	Raw SQL using named `:param` placeholders.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on, or `None` for the connection this gateway is scoped to.

Returns
`list of dict`	One dictionary per row keyed by column name.

Raises
`QueryException`	If the statement fails to execute.

@abstractmethod

def setDefaultName(self, name: str): (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Change the connection used when none is specified.

Parameters
name:`str`	Connection name as declared in the database configuration.

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

Raises
`ConnectionNotFoundException`	If the connection is not declared in the configuration.

@abstractmethod

async def statement(self, sql: str, bindings: dict[str, object] | None = None, name: str | None = None) -> bool: (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Run a raw statement without inspecting its result.

Parameters
sql:`str`	Raw SQL statement, typically DDL or a maintenance command.
bindings:`dict or None, optional`	Values bound to the placeholders of the statement.
name:`str or None, optional`	Named connection to run the statement on, or `None` for the connection this gateway is scoped to.

Returns
`bool`	`True` when the statement executes without errors.

Raises
`QueryException`	If the statement fails to execute.

@abstractmethod

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

overridden in orionis.orm.query_builder.QueryBuilder

Build a fluent, model-less query over a plain table name.

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.
connection:`str or None, optional`	Named connection to run the query against, or `None` for the default connection.

Returns
`IRawQueryBuilder`	Fluent, model-less query builder over the table.

@abstractmethod

def transaction(self, name: str | None = None) -> ITransaction: (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Return a transaction usable as an async context manager.

Parameters
name:`str or None, optional`	Named connection the transaction runs against, or `None` for the default connection.

Returns
`ITransaction`	Context manager committing on success and rolling back on error.

__slots__: tuple = (source) ¶

overridden in orionis.orm.query_builder.QueryBuilder

Undocumented