SparqlModel

Get started

  • Installation
    • Requirements
    • PyPI
    • Optional extras
    • Development install
    • Version pinning
  • Getting started
    • Install
    • Define models
    • Persist and query
    • What’s next

Guides

  • Guides
    • Models and Pydantic validation
      • Why Pydantic
      • Define a model
      • Validation on write
      • Validation on read
      • Pydantic Field kwargs
      • Richer RDF modeling (0.13+)
      • What Pydantic does not cover (yet)
      • TripleModel integration (Option A)
      • Related
    • Sessions and stores
      • Context manager (recommended)
      • Session API at a glance
      • Pending flush queue
      • Identity map
        • Cache control (0.9+)
      • Choosing a store
      • Composition vs reference
      • Threading
      • Next
    • Query DSL
      • Basic filters
      • Boolean composition
      • Multi-hop paths
      • Negation semantics
      • Pagination, sorting, and count
      • Nullable relationships
      • Result helpers
      • 0.13 query features
      • Raw SPARQL
      • Security
      • Next
    • FastAPI integration
      • HttpStore + lifespan
      • In-memory store (tests)
      • Request lifecycle
      • Scoped session pattern (0.9+)
      • Content negotiation
      • Testing
      • Async routes (0.6+)
      • Next
    • Related
  • Real-world examples
    • Overview
    • Run locally
    • Load bundled Turtle
    • Nobel Prize linked data (1901)
    • DCAT open data catalog
    • Wikidata capital cities
    • Schema.org NGO registry
    • TripleModel vs SparqlModel in these examples
    • What’s next
  • SparqlModel ORM guide
    • Two packages, one stack
    • Pydantic integration
    • Choose your package
    • What you import from SparqlModel
    • ORM lifecycle
    • Async session (0.6+)
    • Composition and cascade
    • Query DSL
    • Hydration
    • HttpStore and the local mirror
    • Export and file I/O
    • Current integration status
    • Production readiness
    • When not to use SparqlModel
    • Further reading
  • SparqlModel production guide
    • When to use which store
    • HttpStore mirror model (0.2)
    • Mirror sync (0.12+)
    • HTTP resilience (0.11+)
    • Mirror modes (0.10+)
    • Session per request (FastAPI)
    • Pagination and sorting (0.8+)
    • Identity map and caching
    • Validation and quality
    • Security
    • Monitoring checklist
    • Further reading
  • SparqlModel (ORM) + TripleModel (mapping engine)
    • Choose your package
    • Stack (required dependency)
      • Rules
    • SparqlModel owns (ORM)
    • TripleModel owns (mapping engine)
    • Where to implement a change
      • Heuristic
    • Interim code (retiring)
    • Public ORM API vs TripleModel
    • Dependency pin
    • Integration milestones
    • Testing split
    • Anti-patterns
    • Summary

Reference

  • SparqlModel Technical Specification
    • Overview
  • Production ORM checklist (1.3 GA gate)
    • P0 — Production APIs
    • P1 — SQLModel / SPARQLMojo parity
    • P2 — Advanced
  • SPARQLSession
    • Methods
    • Context manager
    • Properties
    • Session lifecycle (target API)
  • Query builder
    • Query builder (target API)
  • SPARQL compilation
  • Hydration
  • SPARQLModel
    • Validation architecture
  • Relationships
    • Relationships and hydration (target API)
  • Persistence policy
    • put
    • delete
    • Ownership rules
  • Mapping integration (TripleModel)
  • HttpStore
    • HTTP resilience (0.11+)
    • Store protocol (target API)
  • Security (SPARQL generation)
  • Async API (target 0.6)
  • Known limitations
    • Until 0.4 (unified model)
    • HttpStore mirror (0.12+)
    • Permanent constraints
    • Other (current)
  • Optional: export and files
  • FastAPI (optional extra)
  • Feature ownership
  • Maintainer boundaries
  • Package layout
  • Dependencies
  • Related projects
  • API reference
    • Package
      • AsyncHttpStore
        • AsyncHttpStore.__init__()
        • AsyncHttpStore.aclose()
        • AsyncHttpStore.endpoint
        • AsyncHttpStore.graph
        • AsyncHttpStore.graph_store_url
        • AsyncHttpStore.mirror_generation
        • AsyncHttpStore.mirror_mode
        • AsyncHttpStore.namespaces
        • AsyncHttpStore.pull_subjects_into_mirror()
        • AsyncHttpStore.query()
        • AsyncHttpStore.query_method
        • AsyncHttpStore.read_endpoint
        • AsyncHttpStore.sync_mirror()
        • AsyncHttpStore.update_graph()
        • AsyncHttpStore.write_endpoint
      • AsyncMemoryStore
        • AsyncMemoryStore.__init__()
        • AsyncMemoryStore.aclose()
        • AsyncMemoryStore.graph
        • AsyncMemoryStore.namespaces
        • AsyncMemoryStore.query()
        • AsyncMemoryStore.update_graph()
      • AsyncSPARQLSession
        • AsyncSPARQLSession.__init__()
        • AsyncSPARQLSession.add()
        • AsyncSPARQLSession.close()
        • AsyncSPARQLSession.delete()
        • AsyncSPARQLSession.execute()
        • AsyncSPARQLSession.expire()
        • AsyncSPARQLSession.expunge()
        • AsyncSPARQLSession.expunge_all()
        • AsyncSPARQLSession.flush()
        • AsyncSPARQLSession.get()
        • AsyncSPARQLSession.graph
        • AsyncSPARQLSession.hydrate_bindings()
        • AsyncSPARQLSession.merge()
        • AsyncSPARQLSession.namespaces
        • AsyncSPARQLSession.put()
        • AsyncSPARQLSession.query()
        • AsyncSPARQLSession.refresh()
        • AsyncSPARQLSession.rollback_pending()
        • AsyncSPARQLSession.store
      • BackPopulates
        • BackPopulates.__init__()
        • BackPopulates.field
        • BackPopulates.model
      • ConfigurationError
      • Field()
      • HydrationError
      • HttpStore
        • HttpStore.__init__()
        • HttpStore.close()
        • HttpStore.endpoint
        • HttpStore.graph
        • HttpStore.graph_store_url
        • HttpStore.mirror_generation
        • HttpStore.mirror_mode
        • HttpStore.namespaces
        • HttpStore.pull_subjects_into_mirror()
        • HttpStore.query()
        • HttpStore.query_method
        • HttpStore.read_endpoint
        • HttpStore.sync_mirror()
        • HttpStore.update_graph()
        • HttpStore.write_endpoint
      • IRI
        • IRI.compact()
        • IRI.expand()
      • Lang
        • Lang.__init__()
        • Lang.direction
        • Lang.code
      • LangString
        • LangString.__init__()
        • LangString.direction
        • LangString.lang
        • LangString.value
      • MemoryStore
        • MemoryStore.__init__()
        • MemoryStore.graph
        • MemoryStore.mirror_generation
        • MemoryStore.namespaces
        • MemoryStore.query()
        • MemoryStore.update_graph()
      • MultiLangString
        • MultiLangString.__init__()
        • MultiLangString.from_mapping()
        • MultiLangString.get()
        • MultiLangString.values()
        • MultiLangString.by_lang
      • OntologyRegistry
        • OntologyRegistry.__init__()
        • OntologyRegistry.from_graph()
        • OntologyRegistry.from_ttl()
        • OntologyRegistry.inverse_of()
        • OntologyRegistry.load_graph()
        • OntologyRegistry.register_inverse()
        • OntologyRegistry.register_subclasses()
        • OntologyRegistry.subtypes_of()
      • QueryError
      • Relationship()
      • ResourceRef
        • ResourceRef.__init__()
        • ResourceRef.iri
      • SPARQLModel
        • SPARQLModel.ensure_id()
        • SPARQLModel.get_prefixes()
        • SPARQLModel.get_relationship_fields()
        • SPARQLModel.get_scalar_fields()
        • SPARQLModel.iter_sparql_fields()
        • SPARQLModel.model_config
        • SPARQLModel.model_dump_jsonld()
        • SPARQLModel.model_validate_jsonld()
        • SPARQLModel.namespace_registry()
        • SPARQLModel.subject_uri()
        • SPARQLModel.rdf_type
        • SPARQLModel.Rdf
        • SPARQLModel.id
      • SPARQLSession
        • SPARQLSession.__init__()
        • SPARQLSession.add()
        • SPARQLSession.close()
        • SPARQLSession.delete()
        • SPARQLSession.execute()
        • SPARQLSession.expire()
        • SPARQLSession.expunge()
        • SPARQLSession.expunge_all()
        • SPARQLSession.flush()
        • SPARQLSession.from_rdf_file()
        • SPARQLSession.get()
        • SPARQLSession.graph
        • SPARQLSession.hydrate_bindings()
        • SPARQLSession.merge()
        • SPARQLSession.namespaces
        • SPARQLSession.put()
        • SPARQLSession.query()
        • SPARQLSession.refresh()
        • SPARQLSession.rollback_pending()
        • SPARQLSession.store
      • SchemaRegistry
      • SparqlModelError
      • StaleTripleWarning
      • TypedLiteral
        • TypedLiteral.__init__()
        • TypedLiteral.datatype
        • TypedLiteral.from_literal()
        • TypedLiteral.to_literal()
        • TypedLiteral.value
      • inverse_pair()
      • not_()
      • property_eq()
      • property_path()
    • Models and fields
      • SPARQLModelMetaclass
      • SPARQLModel
        • SPARQLModel.model_config
        • SPARQLModel.get_prefixes()
        • SPARQLModel.iter_sparql_fields()
        • SPARQLModel.get_relationship_fields()
        • SPARQLModel.get_scalar_fields()
        • SPARQLModel.ensure_id()
        • SPARQLModel.subject_uri()
        • SPARQLModel.model_dump_jsonld()
        • SPARQLModel.model_validate_jsonld()
      • Field()
      • Relationship()
      • SPARQLFieldMetadata
        • SPARQLFieldMetadata.__init__()
      • field_cardinality_for()
      • get_field_metadata()
      • inverse_pair()
      • is_relationship_field()
      • iter_relationship_values()
      • predicate_uri_for_field()
      • relationship_allows_iri()
      • relationship_is_nullable()
      • relationship_is_ref_link()
      • resolve_related_model()
      • is_compact_iri()
      • is_absolute_iri()
      • IRI
        • IRI.expand()
        • IRI.compact()
      • expand_iri()
      • compact_iri()
      • NamespaceRegistry
        • NamespaceRegistry.__init__()
        • NamespaceRegistry.bind()
        • NamespaceRegistry.sparql_prefixes()
    • Session
      • SPARQLSession
        • SPARQLSession.__init__()
        • SPARQLSession.from_rdf_file()
        • SPARQLSession.flush()
        • SPARQLSession.rollback_pending()
        • SPARQLSession.close()
        • SPARQLSession.expire()
        • SPARQLSession.expunge()
        • SPARQLSession.expunge_all()
        • SPARQLSession.refresh()
        • SPARQLSession.merge()
        • SPARQLSession.add()
        • SPARQLSession.put()
        • SPARQLSession.delete()
        • SPARQLSession.get()
        • SPARQLSession.hydrate_bindings()
        • SPARQLSession.query()
        • SPARQLSession.execute()
      • SessionState
        • SessionState.__init__()
        • SessionState.invalidate_hydration_for_iri()
        • SessionState.remove_pending_for()
        • SessionState.expunge_all()
      • validate_depth()
      • hydrate_from_bindings()
      • hydrate_one()
      • AsyncSPARQLSession
        • AsyncSPARQLSession.__init__()
        • AsyncSPARQLSession.flush()
        • AsyncSPARQLSession.rollback_pending()
        • AsyncSPARQLSession.close()
        • AsyncSPARQLSession.expire()
        • AsyncSPARQLSession.expunge()
        • AsyncSPARQLSession.expunge_all()
        • AsyncSPARQLSession.refresh()
        • AsyncSPARQLSession.merge()
        • AsyncSPARQLSession.add()
        • AsyncSPARQLSession.put()
        • AsyncSPARQLSession.delete()
        • AsyncSPARQLSession.get()
        • AsyncSPARQLSession.hydrate_bindings()
        • AsyncSPARQLSession.query()
        • AsyncSPARQLSession.execute()
      • AsyncQuery
        • AsyncQuery.__init__()
      • sparql_has_prefix_declarations()
      • depth_satisfied()
      • invalidate_subjects()
      • check_stale_add()
      • expunge_impl()
      • expunge_all_impl()
      • refresh_impl()
      • refresh_impl_async()
      • merge_impl()
    • Query and compiler
      • Query
        • Query.__init__()
        • Query.polymorphic()
        • Query.values()
      • CompareOp
      • FieldRef
        • FieldRef.str()
        • FieldRef.lower()
        • FieldRef.upper()
        • FieldRef.__init__()
      • IriStrFieldRef
        • IriStrFieldRef.__init__()
      • IriStrCompare
        • IriStrCompare.__init__()
      • PropertyPathCompare
        • PropertyPathCompare.__init__()
      • CompareExpr
        • CompareExpr.__init__()
      • NotExpr
        • NotExpr.__init__()
      • AndExpr
        • AndExpr.__init__()
      • OrExpr
        • OrExpr.__init__()
      • not_()
      • property_path()
      • property_eq()
      • compile_compare()
      • compile_and_branch()
      • compile_or()
      • compile_where()
    • Stores
      • StoreProtocol
        • StoreProtocol.graph
        • StoreProtocol.query()
        • StoreProtocol.update_graph()
        • StoreProtocol.__init__()
      • MemoryStore
        • MemoryStore.__init__()
        • MemoryStore.mirror_generation
        • MemoryStore.query()
        • MemoryStore.update_graph()
      • HttpStore
        • HttpStore.__init__()
        • HttpStore.mirror_mode
        • HttpStore.query_method
        • HttpStore.graph_store_url
        • HttpStore.mirror_generation
        • HttpStore.sync_mirror()
        • HttpStore.query()
        • HttpStore.pull_subjects_into_mirror()
        • HttpStore.update_graph()
      • AsyncStoreProtocol
        • AsyncStoreProtocol.graph
        • AsyncStoreProtocol.namespaces
        • AsyncStoreProtocol.query()
        • AsyncStoreProtocol.update_graph()
        • AsyncStoreProtocol.aclose()
        • AsyncStoreProtocol.__init__()
      • AsyncMemoryStore
        • AsyncMemoryStore.__init__()
      • AsyncHttpStore
        • AsyncHttpStore.__init__()
        • AsyncHttpStore.mirror_mode
        • AsyncHttpStore.query_method
        • AsyncHttpStore.graph_store_url
        • AsyncHttpStore.mirror_generation
        • AsyncHttpStore.sync_mirror()
        • AsyncHttpStore.query()
        • AsyncHttpStore.pull_subjects_into_mirror()
        • AsyncHttpStore.update_graph()
      • iter_graph_chunks()
      • build_update_chunks()
      • append_query_params()
      • expand_subject_iris()
      • request_with_retry()
      • async_request_with_retry()
      • execute_select()
      • async_execute_select()
      • remove_mirror_subjects()
      • apply_construct_to_mirror()
      • sparql_url()
      • is_select_query()
      • default_graph_store_url()
      • replace_mirror_from_graph()
      • parse_gsp_response()
      • parse_construct_response()
      • fetch_graph_store()
      • async_fetch_graph_store()
    • FastAPI (optional extra)
      • async_http_store_lifespan()
      • async_session_dependency()
      • get_async_session()
      • get_session()
      • http_store_lifespan()
      • init_app()
      • init_async_app()
      • jsonld_response()
      • negotiated_response()
      • session_dependency()
      • turtle_response()
      • init_app()
      • get_session()
      • http_store_lifespan()
      • session_dependency()
      • init_async_app()
      • get_async_session()
      • async_http_store_lifespan()
      • async_session_dependency()
    • Exceptions
      • SparqlModelError
      • ConfigurationError
      • QueryError
      • HydrationError
      • StaleTripleWarning
    • Serializers
      • export_graph()
      • import_graph()
      • export_model()
      • model_to_jsonld()
      • model_from_jsonld()
  • Glossary
  • Troubleshooting
    • execute returns IRIs that get cannot load
    • Stale mirror after an external writer updated the remote
    • Mirror out of date after external bulk load
    • Duplicate triples after UPDATE retry
    • Transient HTTP errors (503 / timeouts)
    • Large put / cascade UPDATE fails or times out
    • SELECT over GET and URL length
    • query().all() returns fewer rows than the remote SELECT
    • Stale data after put
    • Exception in with block leaves session open
    • Pending put not visible in get
    • QueryError on None or wrong model class
    • QueryError: Cannot combine OR and AND
    • Remote and mirror diverge after editing session.graph
    • != behaves unexpectedly
    • URL strings become IRIs
    • RuntimeError: Cannot use a closed SPARQLSession
    • Thread safety / corrupted session state
    • Build / import errors
    • Getting help

Project

  • SparqlModel Roadmap
    • North star
    • Design principle: Pydantic-first
    • Shipped (0.1.x)
      • ORM
      • TripleModel
    • Shipped (0.2.0)
      • Stores (ORM)
      • Session (ORM)
      • Query compiler (ORM)
      • FastAPI (ORM)
      • TripleModel wiring (integration — interim)
      • Persistence polish
    • 0.2 — Operational ORM + adapter foundation
    • 0.3 — Session I/O through TripleModel (interim adapter)
      • Wire session to TripleModel (interim)
      • SparqlModel-only
      • Consume from TripleModel (already in 0.9)
    • 0.4 — Unified model (Option A)
      • Unified model layer
    • 0.5 — Pyoxigraph + TripleModel 0.10
      • Engine and stores
      • Pyoxigraph utilization (audit vs 0.5.8 docs)
        • In use today (keep)
        • Gaps — add to roadmap (by owner)
      • 0.5.1 patch
      • 0.5.2 patch
    • 0.6 — Async end-to-end
      • Store layer
      • Session layer
      • FastAPI
      • Quality
    • Forward roadmap (0.7 → 0.15)
      • At a glance
      • Tracks (what each line of work owns)
      • 0.7 — Delegated file I/O
      • 0.8 — Query lists
      • 0.9 — Session cache control
      • 0.9.1 patch
      • 0.9.2 patch
      • Production HttpStore
      • 0.10.0 — Mirror semantics
        • Phase 0.10 — Mirror semantics
        • Phase 0.11 — HTTP resilience
        • Phase 0.12 — Mirror contract
      • 0.13 — Richer RDF models (SPARQLMojo parity) — shipped 0.13.0
      • 0.14 — Production operations
      • 0.15 — Production GA
    • Future (post-0.15)
    • SQLModel parity checklist
    • SPARQLMojo comparison
      • At a glance (vs SPARQLMojo)
      • SPARQLMojo parity backlog
    • Priorities (forward work)
    • Contributing
  • SparqlModel Project Plan
    • Vision
  • Production ORM definition (1.3 GA north star)
  • Parity tiers
  • Competitive positioning
  • Product positioning
    • SparqlModel (ORM)
    • TripleModel (required dependency)
  • ORM thesis
  • Architecture (Option A)
  • Integration strategy
  • Primary goals
  • Target users
  • Technology stack
  • Releases (summary)
  • Risks
  • Strategy
  • Plan: Fully Async, Rust-Backed RDF for Python
    • Executive summary
    • Problem
    • Vision
    • Positioning
      • What we do not compete with
      • Relationship to SparqlModel 0.5 and 0.6
    • Design principles
    • Architecture
      • Layered stack
      • Rust workspace (proposed crates)
      • Python package layout
    • Execution model
    • Public API (sketch)
      • 1. SparqlClient — remote endpoint
      • 2. AsyncStore protocol (align with SparqlModel)
      • 3. Streaming parse / serialize
      • 4. Term interchange
    • SparqlModel integration
    • Phased delivery
      • Phase 0 — Design & spike (2–4 weeks)
      • Phase 1 — Async HTTP (MVP, 0.1.0)
      • Phase 2 — Streaming I/O (0.2.0)
      • Phase 3 — Embedded async store (0.3.0)
      • Phase 4 — Production hardening (1.0.0)
    • Non-goals (v1)
    • Technology choices
    • Risks and mitigations
    • Open questions
    • Success criteria
    • Suggested next steps
    • Document history
  • Changelog
  • Changelog
    • [Unreleased]
    • [0.13.1] - 2026-06-01
      • Fixed
    • [0.13.0] - 2026-05-22
      • Fixed
      • Added
      • Changed
      • Documentation
    • [0.12.0] - 2026-05-22
      • Added
      • Fixed
      • Documentation
    • [0.11.0] - 2026-05-22
      • Added
      • Changed
      • Documentation
    • [0.10.0] - 2026-05-22
      • Added
      • Changed
      • Fixed
      • Documentation
    • [0.9.2] - 2026-05-21
      • Fixed
      • Changed
      • Documentation
    • [0.9.1] - 2026-05-21
      • Added
      • Fixed
      • Changed
      • Documentation
    • [0.9.0] - 2026-05-21
      • Added
      • Changed
      • Documentation
    • [0.8.1] - 2026-05-21
      • Fixed
      • Changed
      • Documentation
    • [0.8.0] - 2026-05-21
      • Added
      • Changed
      • Documentation
    • [0.7.1] - 2026-05-21
      • Added
      • Documentation
    • [0.7.0] - 2026-05-20
      • Changed
      • Fixed
      • Documentation
      • Tests
      • Notes
    • [0.6.0] - 2026-05-20
      • Added
      • Fixed
      • Documentation
      • Notes
    • [0.5.2] - 2026-05-20
      • Fixed
      • Changed
      • Added
    • [0.5.1] - 2026-05-19
      • Fixed
      • Documentation
    • [0.5.0] - 2026-05-18
      • Added
      • Changed
      • Removed
      • Fixed
    • [0.4.0] - 2026-05-18
      • Added
      • Changed
      • Fixed
      • Migration (0.3 → 0.4)
    • [0.3.0] - 2026-05-18
      • Added
      • Changed
      • Fixed
      • Documentation
    • 0.2.0 - 2026-05-18
      • Added
      • Changed
      • Fixed
      • Documentation
    • 0.1.4 - 2026-05-16
      • Added
      • Changed
      • Documentation
      • Fixed
    • 0.1.3 - 2026-05-16
      • Fixed
      • Documented
    • 0.1.2 - 2026-05-16
      • Changed
    • 0.1.1 - 2026-05-16
      • Fixed
      • Documented
    • 0.1.0 - 2026-05-16
      • Added
  • Building documentation locally
    • Prerequisites
    • HTML build
    • Read the Docs
    • Site structure
SparqlModel
  • Search

© Copyright 2026, SparqlModel Contributors.

Built with Sphinx using a theme provided by Read the Docs.