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

Translate Orionis query plans into engine-executable statements.

This is the only component, together with the connection and the dialect helpers, aware of the underlying SQL toolkit. It converts orionis.orm.schema.TableDefinition objects into engine table metadata (cached per compiler) and query plans into executable statements.

Static Method _combineExpressions Combine compiled clauses while preserving left-to-right grouping.
Static Method _predicateValue Match UUID predicates to textual storage without changing UUID columns.
Static Method _rawElement Compile trusted SQL text with named bindings and an optional alias.
Static Method supportsBatchInsert Check whether multiple rows share a parameter-only batch shape.
Method __init__ Initialize backend settings and compiler-owned table metadata.
Method _aggregateDerived Aggregate the complete compound or grouped query through a derived table.
Method _aggregateExpression Compile an aggregate function over a column or all rows.
Method _applyJoin Extend a FROM clause with the requested join type.
Method _applyOrderingAndPaging Apply a plan's ordering, limit, and offset to a SELECT.
Method _applySelectLock Apply the backend's supported row-lock syntax to a SELECT.
Method _applyUnions Combine union branches and apply global ordering and pagination.
Method _bareNameForIdentifier Extract a bare column name for a matching source identifier.
Method _basicExpression Compile a column-to-value comparison with backend-specific handling.
Method _betweenExpression Compile BETWEEN or NOT BETWEEN with exactly two bounds.
Method _buildSelect Build a SELECT and resolve references to enclosing query sources.
Method _cacheKey Build a table cache key from its physical name and optional schema.
Method _clauseExpression Dispatch a WHERE condition to its matching SQL predicate builder.
Method _clauseValue Compile a SELECT value or return a non-query value unchanged.
Method _collectClauseColumnNames Collect explicit column references from conditions and nested groups.
Method _collectPlanColumnNames Collect explicit column references from the current SELECT plan.
Method _columnComparison Compare two resolved columns using the clause's operator.
Method _columnlessExpression Compile nested groups, raw predicates, and EXISTS subqueries.
Method _columnOptions Build column constraints, identity options and static defaults.
Method _compileSelect Compile every branch while retaining enclosing correlation sources.
Method _ensureRawColumns Declare missing referenced columns on a schemaless table.
Method _ensureReferencedColumns Extend undeclared target metadata with missing foreign-key columns.
Method _ensureReferencedTable Register missing metadata for a single-column foreign-key target.
Method _ensureSelectRawColumns Declare referenced columns for schemaless SELECT and JOIN sources.
Method _joinCondition Combine a join's ON conditions into one boolean expression.
Method _joinConditionExpression Compile an ON condition as a comparison between two columns.
Method _joinSource Build a joined table or an aliased subquery source.
Method _physicalName Build a physical table name by prepending the configured prefix.
Method _projectionElement Compile one projection entry into a SQL expression.
Method _resolveColumn Resolve a column by source qualifier or default table.
Method _resolveSources Build SELECT sources and assemble the FROM clause.
Method _selectProjection Build a SELECT projection from an aggregate or projected entries.
Method _splitQualifiedColumn Split a column reference at its last qualifier separator.
Method _sqlColumn Translate a column definition into SQLAlchemy column metadata.
Method _sqlTable Resolve cached table metadata or rebuild it for a new definition.
Method _sqlType Build a SQLAlchemy type with any required backend variants.
Method _tableConstraints Build table-level keys, foreign keys, and indexes.
Method _validateSelectLock Reject a SELECT row lock when the backend is Redshift.
Method _whereExpression Compile ordered WHERE or HAVING clauses into one predicate.
Method compileCreateTable Compile table metadata into a CREATE TABLE DDL object.
Method compileDelete Compile filtering conditions into a DELETE statement.
Method compileDropTable Compile a DROP TABLE DDL object for a logical table name.
Method compileInsert Compile row mappings into an executable INSERT statement.
Method compileSelect Compile a SELECT plan, including aggregates and union branches.
Method compileUpdate Compile replacement values and filters into an UPDATE statement.
Constant _TYPE_BUILDERS Factories translating logical column definitions into SQLAlchemy types.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _definitions Schema definitions cached for statement compilation.
Instance Variable _driver Orionis backend name for native type, identity, and locking options.
Instance Variable _metadata Compiled metadata used to describe and invoke the registered operation.
Instance Variable _prefix Text prepended to logical table names; empty by default.
Instance Variable _tables Table metadata indexed for query compilation or route lookup.
def _combineExpressions(compile_clause: Callable[..., ColumnElement[bool]], sources: SourceMap, default: SqlSource, clauses: Sequence[WhereClause] | Sequence[JoinCondition]) -> ColumnElement[bool] | None: (source)

Combine compiled clauses while preserving left-to-right grouping.

Ignore the first clause's connector; later connectors join successive clauses.

Parameters
compile_clause:collections.abc.CallableCallable receiving sources, default, and one condition.
sources:orionis.database.compiler.SourceMapSource lookup supplied unchanged to each clause compiler.
default:typing.AnyFallback source supplied to the clause compiler.
clauses:Sequence[WhereClause] | Sequence[JoinCondition]Conditions to compile and combine in their declared order.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClause or NoneCombined predicate, or None for an empty sequence.
def _predicateValue(column: ColumnElement[Any], value: Any) -> Any: (source)

Match UUID predicates to textual storage without changing UUID columns.

Parameters
column:sqlalchemy.sql.elements.ColumnElementResolved column, including its declared SQL type and any alias.
value:typing.AnyPredicate value to bind.
Returns
typing.AnyCanonical UUID text for textual columns; the original value otherwise.
def _rawElement(raw: RawExpression) -> ColumnElement[Any]: (source)

Compile trusted SQL text with named bindings and an optional alias.

Treat SQL text as trusted input; only values in bindings are parameterized. Aliased expressions remain addressable in derived queries.

Parameters
raw:orionis.orm.query.expressions.RawExpressionSQL fragment, named parameter values, and optional projection alias.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClauseText clause or labeled expression; supplied bindings use unique parameters.
def supportsBatchInsert(plan: InsertPlan) -> bool: (source)

Check whether multiple rows share a parameter-only batch shape.

Check row shapes and values without compiling the INSERT statement.

Parameters
plan:orionis.orm.query.InsertPlanInsert plan with row mappings and optional declared table columns.
Returns
boolTrue when the batch precheck accepts multiple rows with matching keys and no SQLAlchemy expressions; False otherwise.
def __init__(self, prefix: str = '', *, driver: str | None = None): (source)

Initialize backend settings and compiler-owned table metadata.

Parameters
prefix:str, optionalText prepended to logical table names; empty by default.
driver:str or None, optionalOrionis backend name for native type, identity, and locking options.
Returns
NoneNo return value.
def _aggregateDerived(self, plan: SelectPlan, outer_sources: SourceMap) -> Select[Any]: (source)

Aggregate the complete compound or grouped query through a derived table.

Parameters
plan:orionis.orm.query.SelectPlanQuery whose aggregate must consume its complete projected row set.
outer_sources:orionis.database.compiler.SourceMapEnclosing sources retained while compiling correlated branches.
Returns
sqlalchemy.sql.SelectAggregate over the original rows without read ordering or pagination.
def _aggregateExpression(self, sources: SourceMap, default: SqlSource, aggregate: AggregateClause) -> ColumnElement[Any]: (source)

Compile an aggregate function over a column or all rows.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for an unqualified aggregate column.
aggregate:orionis.orm.query.AggregateClauseAggregate function and column reference, or * for COUNT.
Returns
sqlalchemy.sql.elements.ColumnElementCOUNT expression or the requested function applied to a resolved column.
Raises
orionis.database.QueryExceptionIf a non-COUNT aggregate targets * or a column cannot be resolved.
def _applyJoin(self, from_clause: SqlSource, sources: SourceMap, join: JoinExpression) -> tuple[SqlSource, str, SqlSource]: (source)

Extend a FROM clause with the requested join type.

Emulate RIGHT JOIN by swapping sources in a LEFT JOIN.

Parameters
from_clause:typing.AnyFROM/JOIN expression built before this join.
sources:orionis.database.compiler.SourceMapExisting sources used to resolve ON-clause column references.
join:orionis.orm.query.expressions.JoinExpressionJoined source, join type, and optional ON conditions.
Returns
tuple of (typing.Any, str, typing.Any)Extended FROM clause, joined identifier, and joined source.
Raises
orionis.database.QueryExceptionIf a subquery alias is missing or ON conditions are absent or invalid.
def _applyOrderingAndPaging(self, sources: SourceMap, default: SqlSource, statement: Select[Any], plan: SelectPlan) -> Select[Any]: (source)

Apply a plan's ordering, limit, and offset to a SELECT.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for unqualified ordering columns.
statement:sqlalchemy.sql.SelectSELECT statement to extend without mutating it.
plan:orionis.orm.query.SelectPlanOrdering clauses and optional limit and offset values.
Returns
sqlalchemy.sql.SelectSELECT with all requested sorting and pagination clauses applied.
Raises
orionis.database.QueryExceptionIf an ordering column or its source cannot be resolved.
def _applySelectLock(self, statement: Select[Any], default: SqlSource, plan: SelectPlan) -> Select[Any]: (source)

Apply the backend's supported row-lock syntax to a SELECT.

Parameters
statement:sqlalchemy.sql.SelectQuery whose projection and conditions are already compiled.
default:orionis.database.compiler.SqlSourceMain source receiving SQL Server table hints.
plan:orionis.orm.query.SelectPlanValidated plan containing the optional lock mode.
Returns
sqlalchemy.sql.SelectOriginal statement or its backend-specific locked variant.
def _applyUnions(self, statement: Select[Any], plan: SelectPlan, outer_sources: SourceMap) -> Select[Any]: (source)

Combine union branches and apply global ordering and pagination.

Flatten consecutive operators of the same kind; preserve left-to-right grouping when switching between UNION and UNION ALL.

Parameters
statement:sqlalchemy.sql.SelectBase SELECT without the owning plan's unions, ordering, or paging.
plan:orionis.orm.query.SelectPlanSELECT plan containing at least one union branch.
outer_sources:orionis.database.compiler.SourceMapEnclosing sources retained by each branch.
Returns
sqlalchemy.sql.SelectSELECT over combined rows with the owning plan's order and bounds.
def _bareNameForIdentifier(self, name: str, identifier: str) -> str | None: (source)

Extract a bare column name for a matching source identifier.

Parameters
name:strUnqualified or dot-qualified column reference.
identifier:strAlias or logical table name accepted as the qualifier.
Returns
str or NoneBare name for unqualified or matching references; otherwise None.
def _basicExpression(self, column: ColumnElement[Any], clause: WhereClause) -> ColumnElement[bool]: (source)

Compile a column-to-value comparison with backend-specific handling.

Translate None equality into IS NULL or IS NOT NULL. Use DBMS_LOB.COMPARE for Oracle text equality.

Parameters
column:sqlalchemy.sql.elements.ColumnElementColumn expression, including its SQL type for backend handling.
clause:orionis.orm.query.WhereClauseComparison operator and bound value, including None.
Returns
sqlalchemy.sql.elements.ColumnElementNULL check, text comparison, pattern predicate, or ordinary comparison.
Raises
orionis.database.QueryExceptionIf the comparison operator has no supported handler.
def _betweenExpression(self, column: ColumnElement[Any], clause: WhereClause) -> ColumnElement[bool]: (source)

Compile BETWEEN or NOT BETWEEN with exactly two bounds.

Parameters
column:sqlalchemy.sql.elements.ColumnElementLeft-hand column expression tested against the range.
clause:orionis.orm.query.WhereClauseRange condition with lower and upper boundary values.
Returns
sqlalchemy.sql.elements.ColumnElementInclusive range predicate, negated for NOT BETWEEN.
Raises
orionis.database.QueryExceptionIf the supplied value does not contain exactly two boundaries.
def _buildSelect(self, plan: SelectPlan, outer_sources: SourceMap) -> Select[Any]: (source)

Build a SELECT and resolve references to enclosing query sources.

Parameters
plan:orionis.orm.query.SelectPlanSELECT description whose sources and clauses are compiled.
outer_sources:orionis.database.compiler.SourceMapSource lookup from the enclosing query, or an empty mapping.
Returns
sqlalchemy.sql.SelectSELECT with projection, filters, grouping, paging, and requested locks.
Raises
orionis.database.QueryExceptionIf references or clauses are invalid, or a Redshift lock is requested.
def _cacheKey(self, physical: str, schema: str | None) -> str: (source)

Build a table cache key from its physical name and optional schema.

Parameters
physical:strTable name including the configured prefix.
schema:str or NoneSchema qualifier, or None for an unqualified cache key.
Returns
strSchema-qualified physical name, or the physical name without a schema.
def _clauseExpression(self, sources: SourceMap, default: SqlSource, clause: WhereClause) -> ColumnElement[bool]: (source)

Dispatch a WHERE condition to its matching SQL predicate builder.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for unqualified column names.
clause:orionis.orm.query.WhereClauseCondition type, column reference, operator, and comparison value.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClauseCompiled condition, including nested, raw, and subquery predicates.
Raises
orionis.database.QueryExceptionIf the clause type, references, comparison operator, or range shape is invalid.
def _clauseValue(self, sources: SourceMap, value: Any) -> Any: (source)

Compile a SELECT value or return a non-query value unchanged.

Parameters
sources:orionis.database.compiler.SourceMapEnclosing query sources available for subquery correlation.
value:typing.AnyCondition value, which may itself be a SELECT plan.
Returns
typing.AnyCompiled SELECT for a plan value; the original object otherwise.
Raises
orionis.database.QueryExceptionIf a nested SELECT contains invalid clauses or unresolved references.
def _collectClauseColumnNames(self, clauses: Sequence[WhereClause], names: set[str]): (source)

Collect explicit column references from conditions and nested groups.

Parameters
clauses:collections.abc.Sequence of orionis.orm.query.WhereClauseWHERE or HAVING conditions to inspect recursively.
names:set of strMutable accumulator for left-hand and column-comparison references.
Returns
NoneNo return value.
def _collectPlanColumnNames(self, plan: SelectPlan) -> set[str]: (source)

Collect explicit column references from the current SELECT plan.

Inspect projection names, conditions, ordering, grouping, aggregates, and joins without parsing raw SQL or traversing subquery plans.

Parameters
plan:orionis.orm.query.SelectPlanSELECT plan whose direct references will be collected.
Returns
set of strQualified and unqualified names used by the current plan's clauses.
def _columnComparison(self, sources: SourceMap, default: SqlSource, column: ColumnElement[Any], clause: WhereClause) -> ColumnElement[bool]: (source)

Compare two resolved columns using the clause's operator.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for the right-hand column reference.
column:sqlalchemy.sql.elements.ColumnElementAlready-resolved left-hand column expression.
clause:orionis.orm.query.WhereClauseComparison operator and right-hand column reference.
Returns
sqlalchemy.sql.elements.ColumnElementBoolean comparison between the two column expressions.
Raises
orionis.database.QueryExceptionIf the right-hand column cannot be resolved or the operator is unsupported.
def _columnlessExpression(self, sources: SourceMap, default: SqlSource, clause: WhereClause) -> ColumnElement[bool] | None: (source)

Compile nested groups, raw predicates, and EXISTS subqueries.

Represent an empty nested group as a true predicate.

Parameters
sources:orionis.database.compiler.SourceMapSources available for column resolution and subquery correlation.
default:typing.AnyFallback source for unqualified names inside nested conditions.
clause:orionis.orm.query.WhereClauseCondition whose type determines whether this helper can handle it.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClause or NonePredicate for a supported kind, or None for a column-based kind.
def _columnOptions(self, definition: ColumnDefinition, column_type: TypeEngine[Any]) -> dict[str, Any]: (source)

Build column constraints, identity options and static defaults.

Parameters
definition:orionis.orm.schema.column.ColumnDefinitionLogical column flags and client default value.
column_type:sqlalchemy.types.TypeEngineResolved type used to render a static server default.
Returns
dict[str, typing.Any]Keyword arguments passed to the SQLAlchemy column constructor.
def _compileSelect(self, plan: SelectPlan, outer_sources: SourceMap) -> Select[Any] | CompoundSelect: (source)

Compile every branch while retaining enclosing correlation sources.

Parameters
plan:orionis.orm.query.SelectPlanQuery description, including aggregation and union branches.
outer_sources:orionis.database.compiler.SourceMapEnclosing sources available to every nested branch.
Returns
sqlalchemy.sql.Select or sqlalchemy.sql.CompoundSelectComplete query with its requested branches and global bounds.
def _ensureRawColumns(self, table: TableDefinition, alias: str | None, names: set[str]): (source)

Declare missing referenced columns on a schemaless table.

Declare columns before creating aliases, whose column collections are cached.

Parameters
table:orionis.orm.schema.TableDefinitionTable definition; declared schemas are left unchanged.
alias:str or NoneQuery alias used to match qualified references, or None.
names:set of strCollected qualified or unqualified references from the owning plan.
Returns
NoneNo return value.
def _ensureReferencedColumns(self, table_name: str, columns: Sequence[str]): (source)

Extend undeclared target metadata with missing foreign-key columns.

Keep declared schemas authoritative while extending temporary targets.

Parameters
table_name:strLogical table name, optionally qualified as schema.table.
columns:collections.abc.Sequence of strTarget columns to declare with temporary integer types.
Returns
NoneNo return value.
def _ensureReferencedTable(self, reference: ForeignReference): (source)

Register missing metadata for a single-column foreign-key target.

Parameters
reference:orionis.orm.schema.constraints.ForeignReferenceLogical target table, optional schema qualifier, and referenced column.
Returns
NoneNo return value.
def _ensureSelectRawColumns(self, plan: SelectPlan): (source)

Declare referenced columns for schemaless SELECT and JOIN sources.

Parameters
plan:orionis.orm.query.SelectPlanSELECT plan supplying source definitions and column references.
Returns
NoneNo return value.
def _joinCondition(self, sources: SourceMap, joined_name: str, joined_source: SqlSource, join: JoinExpression) -> ColumnElement[bool]: (source)

Combine a join's ON conditions into one boolean expression.

Parameters
sources:orionis.database.compiler.SourceMapSources available before adding the joined source.
joined_name:strIdentifier used to qualify columns from the new source.
joined_source:typing.AnyTable or derived query introduced by this join.
join:orionis.orm.query.expressions.JoinExpressionJoin description containing one or more ON conditions.
Returns
sqlalchemy.sql.elements.ColumnElementON expression, using the joined source for unqualified column names.
Raises
orionis.database.QueryExceptionIf ON conditions are absent, references are unknown, or operators are unsupported.
def _joinConditionExpression(self, sources: SourceMap, default: SqlSource, condition: JoinCondition) -> ColumnElement[bool]: (source)

Compile an ON condition as a comparison between two columns.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnySource used to resolve unqualified column names.
condition:orionis.orm.query.expressions.JoinConditionLeft reference, comparison operator, and right reference.
Returns
sqlalchemy.sql.elements.ColumnElementBoolean comparison between the resolved column expressions.
Raises
orionis.database.QueryExceptionIf either reference is unknown or the comparison operator is unsupported.
def _joinSource(self, join: JoinExpression) -> tuple[str, SqlSource]: (source)

Build a joined table or an aliased subquery source.

Parameters
join:orionis.orm.query.expressions.JoinExpressionTable or SELECT plan to join, with an optional source alias.
Returns
tuple of (str, typing.Any)Source identifier and table, table alias, or compiled derived query.
Raises
orionis.database.QueryExceptionIf a subquery has no alias or its SELECT plan cannot be compiled.
def _physicalName(self, name: str) -> str: (source)

Build a physical table name by prepending the configured prefix.

Parameters
name:strLogical table name, without the connection prefix.
Returns
strConfigured prefix concatenated with name without normalization.
def _projectionElement(self, sources: SourceMap, default: SqlSource, entry: str | SubQueryColumn | RawExpression) -> ColumnElement[Any]: (source)

Compile one projection entry into a SQL expression.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for unqualified column names.
entry:str | SubQueryColumn | RawExpressionColumn reference, correlated scalar subquery, or trusted SQL fragment.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClauseResolved column, labeled scalar subquery, or compiled raw expression.
def _resolveColumn(self, sources: SourceMap, default: SqlSource, name: str) -> ColumnElement[Any]: (source)

Resolve a column by source qualifier or default table.

Look up qualified references in sources and unqualified names in default.

Parameters
sources:orionis.database.compiler.SourceMapAvailable tables or derived sources indexed by query identifier.
default:typing.AnySource used for unqualified column names.
name:strBare column name or dot-qualified source reference.
Returns
sqlalchemy.sql.elements.ColumnElementColumn exposed by the selected source's column collection.
Raises
orionis.database.QueryExceptionIf the source identifier or column name is unknown.
def _resolveSources(self, plan: SelectPlan) -> tuple[SqlSource, SourceMap, SqlSource]: (source)

Build SELECT sources and assemble the FROM clause.

Index each source by its alias, or by its logical table name when no alias is supplied.

Parameters
plan:orionis.orm.query.SelectPlanMain table, optional alias, and ordered join descriptions.
Returns
tuple of (typing.Any, orionis.database.compiler.SourceMap, typing.Any)Main source, source lookup map, and complete FROM/JOIN expression.
Raises
orionis.database.QueryExceptionIf a joined source or its ON conditions cannot be compiled.
def _selectProjection(self, default: SqlSource, sources: SourceMap, plan: SelectPlan) -> Select[Any]: (source)

Build a SELECT projection from an aggregate or projected entries.

Parameters
default:typing.AnyMain query source and fallback for unqualified references.
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
plan:orionis.orm.query.SelectPlanAggregate, explicit projections, or default table selection.
Returns
sqlalchemy.sql.SelectSELECT of the requested projection; use literal * for raw tables.
def _splitQualifiedColumn(self, name: str) -> tuple[str | None, str]: (source)

Split a column reference at its last qualifier separator.

Parameters
name:strBare column name or dot-qualified source and column reference.
Returns
tuple of (str or None, str)Qualifier and final column segment, with None for a bare name.
def _sqlColumn(self, definition: ColumnDefinition, name: str | None = None) -> SqlColumn[Any]: (source)

Translate a column definition into SQLAlchemy column metadata.

Apply backend identity options and emit non-null static defaults both as client defaults and SQL server defaults.

Parameters
definition:orionis.orm.schema.column.ColumnDefinitionType options, constraints, foreign key, defaults, and identity settings.
name:str or None, optionalOverride the definition's name; use definition.name when None.
Returns
sqlalchemy.ColumnColumn with resolved type, constraints, defaults, and backend options.
Raises
orionis.database.QueryExceptionIf the logical column type has no registered SQL type builder.
orionis.database.MissingDatabaseDependencyExceptionIf Redshift column options require a missing dialect package.
def _sqlTable(self, definition: TableDefinition) -> Table: (source)

Resolve cached table metadata or rebuild it for a new definition.

Reuse metadata for raw definitions or the same declared definition instance; rebuild it for a different definition with declared columns. Treat a declared definition and its columns as stable after compilation. In-place edits are not tracked; use a new definition for a schema version.

Parameters
definition:orionis.orm.schema.TableDefinitionLogical table description, including columns, constraints, and schema.
Returns
sqlalchemy.TablePrefixed table registered in this compiler's metadata and table cache.
Raises
orionis.database.QueryExceptionIf a column type has no registered SQL type builder.
def _sqlType(self, definition: ColumnDefinition) -> TypeEngine[Any]: (source)

Build a SQLAlchemy type with any required backend variants.

Parameters
definition:orionis.orm.schema.column.ColumnDefinitionLogical column type and its conversion or precision options.
Returns
sqlalchemy.types.TypeEngineConfigured type, with Oracle FLOAT precision or SQLite auto-increment variants when applicable.
Raises
orionis.database.QueryExceptionIf no builder is registered for the declared column type.
def _tableConstraints(self, definition: TableDefinition) -> list[Any]: (source)

Build table-level keys, foreign keys, and indexes.

Parameters
definition:orionis.orm.schema.TableDefinitionComposite primary key, unique constraints, foreign keys, and indexes.
Returns
list of typing.AnySQLAlchemy schema items with prefixed foreign-key targets and generated names for unnamed indexes.
def _validateSelectLock(self, plan: SelectPlan): (source)

Reject a SELECT row lock when the backend is Redshift.

Parameters
plan:orionis.orm.query.SelectPlanCurrent SELECT plan whose lock setting is checked.
Returns
NoneNo return value.
Raises
orionis.database.QueryExceptionIf plan.lock is set for the Redshift backend.
def _whereExpression(self, sources: SourceMap, default: SqlSource, clauses: Sequence[WhereClause]) -> ColumnElement[bool] | None: (source)

Compile ordered WHERE or HAVING clauses into one predicate.

Use each clause after the first to select its AND or OR connector.

Parameters
sources:orionis.database.compiler.SourceMapSources indexed by alias or logical table name.
default:typing.AnyFallback source for unqualified column names.
clauses:collections.abc.Sequence of orionis.orm.query.WhereClauseOrdered conditions and their boolean connectors.
Returns
sqlalchemy.sql.elements.ColumnElement or TextClause or NoneCompiled predicate, or None when no clauses are supplied.
Raises
orionis.database.QueryExceptionIf a condition has unknown references or unsupported clause semantics.
def compileCreateTable(self, definition: TableDefinition, *, if_not_exists: bool = True) -> Executable: (source)

Compile table metadata into a CREATE TABLE DDL object.

Parameters
definition:orionis.orm.schema.TableDefinitionLogical table name, columns, constraints, schema, and comment.
if_not_exists:bool, optionalRequest IF NOT EXISTS in the generated DDL. Defaults to True.
Returns
sqlalchemy.sql.expression.ExecutableCREATE TABLE object using the compiler's prefix and cached metadata.
Raises
orionis.database.QueryExceptionIf a declared column type has no SQL type builder.
def compileDelete(self, plan: DeletePlan) -> Delete: (source)

Compile filtering conditions into a DELETE statement.

Parameters
plan:orionis.orm.query.DeletePlanTarget table and WHERE conditions selecting rows to delete.
Returns
sqlalchemy.sql.DeleteDELETE filtered by the plan's conditions, or unrestricted without them.
Raises
orionis.database.QueryExceptionIf column references, types, or filtering conditions cannot be compiled.
def compileDropTable(self, name: str, schema: str | None = None, *, if_exists: bool = True) -> Executable: (source)

Compile a DROP TABLE DDL object for a logical table name.

Parameters
name:strLogical name to prefix before resolving table metadata.
schema:str or None, optionalOwning schema, or None to use the default schema.
if_exists:bool, optionalRequest IF EXISTS in the generated DDL. Defaults to True.
Returns
sqlalchemy.sql.expression.ExecutableDROP TABLE object using cached metadata or a lightweight table stub.
def compileInsert(self, plan: InsertPlan, *, parameterized: bool = False) -> Insert: (source)

Compile row mappings into an executable INSERT statement.

Parameters
plan:orionis.orm.query.InsertPlanTarget table and one or more row mappings.
parameterized:bool, optionalLeave values to execution-time bindings. Defaults to False.
Returns
sqlalchemy.sql.InsertINSERT with attached row values, or a parameterized template. Parameterized PostgreSQL statements include RETURNING 1.
Raises
orionis.database.QueryExceptionIf the plan has no rows or a column type has no SQL type builder.
def compileSelect(self, plan: SelectPlan) -> Select[Any] | CompoundSelect: (source)

Compile a SELECT plan, including aggregates and union branches.

Use a derived query for aggregates over unions and COUNT(*) over distinct or grouped results.

Parameters
plan:orionis.orm.query.SelectPlanProjection, sources, conditions, grouping, unions, paging, and locks.
Returns
sqlalchemy.sql.Select or sqlalchemy.sql.CompoundSelectExecutable SELECT; union branches are wrapped in a derived table.
Raises
orionis.database.QueryExceptionIf sources or columns are unknown, clauses are invalid, or a Redshift row lock is requested.
def compileUpdate(self, plan: UpdatePlan) -> Update: (source)

Compile replacement values and filters into an UPDATE statement.

Parameters
plan:orionis.orm.query.UpdatePlanTarget table, nonempty assignment mapping, and WHERE conditions.
Returns
sqlalchemy.sql.UpdateUPDATE filtered by the plan's conditions, or unrestricted without them.
Raises
orionis.database.QueryExceptionIf assignments are empty or columns, types, or conditions are invalid.
_TYPE_BUILDERS: dict = (source)

Factories translating logical column definitions into SQLAlchemy types.

Value
{ColumnType.INTEGER: (lambda _c: sqlalchemy.Integer()),
 ColumnType.BIG_INTEGER: (lambda _c: sqlalchemy.BigInteger()),
 ColumnType.SMALL_INTEGER: (lambda _c: sqlalchemy.SmallInteger()),
 ColumnType.STRING: (lambda c: sqlalchemy.String(c.length, c.collation)),
 ColumnType.TEXT: (lambda c: sqlalchemy.Text(c.length, c.collation)),
 ColumnType.UNICODE: (lambda c: sqlalchemy.Unicode(c.length, c.collation)),
 ColumnType.UNICODE_TEXT: (lambda c: sqlalchemy.UnicodeText(c.length, c.collatio↵
...
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_definitions: dict[str, TableDefinition] = (source)

Schema definitions cached for statement compilation.

Orionis backend name for native type, identity, and locking options.

_metadata = (source)

Compiled metadata used to describe and invoke the registered operation.

Text prepended to logical table names; empty by default.

_tables: dict[str, Table] = (source)

Table metadata indexed for query compilation or route lookup.