Skip to Content
ReferenceSPARQL

SPARQL

Relata exposes a governed SPARQL door at /sparql. It answers a deliberate subset of SPARQL 1.1 over the KnowledgeTriple store, on the same auth and provenance path as every other protocol door.

  • Endpoint: GET or POST /sparql
  • Auth: bearer token (Authorization: Bearer $RELATA_BEARER_TOKEN) — the door verifies auth on both verbs.
  • Data: the KnowledgeTriple type (subject, predicate, object).

Supported subset

The door supports a single Basic Graph Pattern (BGP) with an optional LIMIT. This is the honest surface — Relata translates SPARQL to its governed SQL bridge, so anything the bridge can’t express is rejected rather than silently mis-answered.

FeatureStatus
SELECT with a single triple pattern✅ Supported
Variable subject / predicate / object✅ Supported
LIMIT n✅ Supported
Multi-pattern BGP (joins)⚠️ Parses, then rejected by the SQL bridge
FILTER / OPTIONAL / ORDER BY / UNION❌ Not supported

For multi-hop graph questions use the SQL graph operators (PATHS_BETWEEN, NETWORK_EXPAND) — see the SQL Reference.

Examples

A single Basic Graph Pattern — “all objects Alice is related to”:

SELECT ?predicate ?object
WHERE { "Alice" ?predicate ?object }
LIMIT 25

Over HTTP:

curl -X POST http://localhost:9090/sparql \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -H "Content-Type: application/sparql-query" \
  --data 'SELECT ?p ?o WHERE { "Alice" ?p ?o } LIMIT 25'

GET form (query string):

curl -G http://localhost:9090/sparql \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  --data-urlencode 'query=SELECT ?s ?o WHERE { ?s "KNOWS" ?o } LIMIT 10'

Triple schema

SPARQL reads the KnowledgeTriple type. Each triple is a governed, bi-temporal row like any other Relata data — so a SPARQL read honours ACL, org isolation, and AS OF history through the SQL bridge it compiles to.

PositionColumnNotes
SubjectsubjectThe entity the statement is about
PredicatepredicateThe relationship / property
ObjectobjectThe value or related entity

Why a subset?

A governed database cannot hand an untrusted query planner direct access to storage. Every SPARQL query is compiled to the same policy-checked SQL the rest of the engine runs, so the subset is exactly what that bridge can express safely. Multi-pattern joins and FILTER are the roadmap items; the single-BGP core is production-ready and auth-gated today.

See also

Last updated on
SQL ReferenceMCP