ontosql 0.5.0

Semantic data access for SQL — map ontology-shaped models onto real schemas with explicit OntoMapper bindings (import ontosql)

OntoSQL

Semantic CRUD for SQL-first Python apps — SQLModel tables, Pydantic ontology models, explicit mappers, optional JSON-LD/RDF export.

0.5.x beta — API stability tiers in SPECS; semver guarantees begin at 1.0. Pin versions in production.

Not a SPARQL database or OBDA query engine. RDF and graph sync are optional extras.

Real databases rarely match ontology shapes one-to-one. OntoSQL separates physical SQLModel tables from semantic Pydantic entities and connects them with explicit mappers. Application code uses semantic types; OntoSQL compiles SQL on the backend.

Install

pip install ontosql
pip install "ontosql[async,fastapi]"   # optional extras — see docs

Requirements: Python 3.10+. See Compatibility.

Start here

I want to…	Go to
Try CRUD in 5 minutes (pip only)	Quick start
Pick a path (async, FastAPI, hybrid)	Start here
Understand the design	Architecture
Decide if OntoSQL fits	When to use OntoSQL
Evaluate for production	Security · Compatibility · Enterprise adoption

Full docs: ontosql.readthedocs.io

Minimal example

from sqlmodel import Field, Session, SQLModel, create_engine
from ontosql import Map, OntoMapper, OntoModel, OntoSession, onto_property

class PersonRow(SQLModel, table=True):
    __tablename__ = "people"
    id: int | None = Field(default=None, primary_key=True)
    name: str

class Person(OntoModel):
    type_iri = "schema:Person"
    iri_template = "https://data.example.org/person/{id}"
    id: int
    name: str = onto_property("schema:name")

class PersonMap(OntoMapper[Person]):
    entity = Person
    id = Map(PersonRow.id)
    name = Map(PersonRow.name, property="schema:name")

engine = create_engine("sqlite://")
SQLModel.metadata.create_all(engine)
with Session(engine) as raw:
    raw.add(PersonRow(id=1, name="Ada Lovelace"))
    raw.commit()
# Demo seeds via SQLModel; production code typically uses session.save() — see quickstart.

with OntoSession(engine, maps=[PersonMap]) as session:
    print(session.get(Person, identity=1).name)

Copy the full Person/Organization walkthrough from the quick start.

Ecosystem

Optional RDF export uses TripleModel. Graph-native apps can pair OntoSQL with SparqlModel. See Ecosystem.

Examples (repository clone)

The examples/ directory is not in the PyPI wheel:

git clone https://github.com/eddiethedean/ontosql.git
cd ontosql && pip install -e ".[dev]"
python examples/person_org_demo.py

Script	What it teaches
person_org_demo.py	Sync CRUD round-trip
person_org_async.py	Async session
hybrid_person_org.py	Graph sync, import
person_org_api_production.py	Production FastAPI pattern

See examples/README.md for layout and how _bootstrap.py works.

Development

pip install -e ".[dev]"
ruff check src tests && ty check && pytest --cov=ontosql --cov-fail-under=90

See Contributing and Releasing.

License

MIT — see LICENSE.