Skip to content

Session API

Generated from docstrings. For stability tiers and behavioral contract, see SPECS.md.

OntoSession

ontosql.session.sync.OntoSession

Bases: SessionBase

Synchronous unit of work for semantic CRUD over SQL.

Always use as a context manager::

with OntoSession(engine, maps=[...]) as session:
    ...

rollback 

rollback(*, clear_uow: bool = True) -> None

Roll back the current SQLAlchemy transaction.

Clears the unit-of-work queue by default (clear_uow=True). See docs/internals/session-lifecycle.md.

create_tables 

create_tables(*models: type[SQLModel]) -> None

Create physical tables (convenience for tests).

flush 

flush() -> None

Apply pending save/delete plans; stops on first error (unprocessed queue preserved).

AsyncOntoSession

ontosql.session.async_session.AsyncOntoSession

Bases: SessionBase

Async unit of work for semantic CRUD over SQL.

rollback async 

rollback(*, clear_uow: bool = True) -> None

Roll back the current SQLAlchemy transaction.

Clears the unit-of-work queue by default (clear_uow=True). See docs/internals/session-lifecycle.md.

create_tables 

create_tables(*models: type[SQLModel]) -> None

Create physical tables (convenience for tests).

flush async 

flush() -> None

Apply pending save/delete plans; stops on first error (unprocessed queue preserved).

Pagination

ontosql.session.pagination.Page dataclass

Bases: Generic[T]

Paginated query result.

ontosql.session.pagination.paginate 

paginate(session: Any, entity_type: type[T], *, where: Any | None = None, order_by: Any | None = None, limit: int = 20, offset: int = 0, include_total: bool = True) -> Page[T]

Return a page of entities from a synchronous OntoSession.

ontosql.session.pagination.paginate_async async 

paginate_async(session: Any, entity_type: type[T], *, where: Any | None = None, order_by: Any | None = None, limit: int = 20, offset: int = 0, include_total: bool = True) -> Page[T]

Return a page of entities from an AsyncOntoSession.

Graph sync errors

ontosql.session.graph_sync.GraphSyncError

Bases: Exception

Raised when graph sync fails after SQL commit (split-brain risk).

ontosql.session.graph_sync.GraphSyncFailure dataclass

A single graph sync operation that failed after SQL commit.