SPARQL

Relata exposes a SPARQL 1.1 basic SELECT read endpoint (/sparql) that translates queries to SQL over the provenance graph's triples view and executes them through the governed query path. Available since v0.9.

Conformance: SPARQL 1.1 basic SELECT — BGP triple patterns + LIMIT. This is a deliberate subset, not a full SPARQL 1.2 processor. Full SPARQL 1.2 processing requires the sparql-rdf feature flag (spargebra), not yet in workspace dependencies. For the full query surface, use SQL.

Endpoint

Method	Path	Body / Query
`GET`	`/sparql`	`?query=<url-encoded SPARQL>`
`POST`	`/sparql`	`Content-Type: application/sparql-query` (body is the query)

Both return JSON.

GET

curl "http://localhost:9090/sparql?query=SELECT%20%3Fs%20%3Fp%20%3Fo%20WHERE%20%7B%20%3Fs%20%3Chttp%3A%2F%2Fwww.w3.org%2Fns%2Fprov%23wasAttributedTo%3E%20%3Fo%20%7D%20LIMIT%2010"

Equivalent unencoded query:

SELECT ?s ?p ?o WHERE {
  ?s <http://www.w3.org/ns/prov#wasAttributedTo> ?o
} LIMIT 10

POST

curl -X POST http://localhost:9090/sparql \
  -H "Content-Type: application/sparql-query" \
  -d "SELECT ?s ?o WHERE { ?s <http://www.w3.org/ns/prov#wasDerivedFrom> ?o } LIMIT 5"

Authentication

Same as /query. When RELATA_BEARER_TOKEN is set, include it:

curl -H "Authorization: Bearer $TOKEN" "http://localhost:9090/sparql?query=..."

Response format

{
  "sparql": "SELECT ?s WHERE { ?s ?p ?o } LIMIT 5",
  "sql": "SELECT * FROM triples LIMIT 5",
  "rows": 2,
  "columns": ["s", "p", "o"],
  "data": [
    {"s": "urn:relata:row:...", "p": "...", "o": "..."}
  ],
  "processing_time_ms": 3
}

The translated SQL is echoed in the sql field, and processing_time_ms follows the Meilisearch/Typesense convention.

Supported subset

The translator (relata_query's SPARQL→SQL translator) covers:

Construct	Status
`SELECT ?vars WHERE { ?s <pred> ?o }`	Supported
Multiple BGP triple patterns (inner join)	Supported
`LIMIT n`	Supported
`OPTIONAL`	400 — use `LEFT JOIN` in SQL
`FILTER`	400 — add the predicate to SQL `WHERE`
`GRAPH`, `CONSTRUCT`, `ASK`, `DESCRIBE`	400
`ORDER BY`, `OFFSET`, `DISTINCT`, `UNION`	400 — use SQL equivalents
Federated `SERVICE`	400 — Relata is single-source

RDF / PROV-O predicates

The provenance graph is exposed via the PROV-O vocabulary (http://www.w3.org/ns/prov#):

Predicate	Meaning
`prov:wasGeneratedBy`	Activity that produced the row
`prov:wasDerivedFrom`	Prior assertion the row derives from
`prov:wasAttributedTo`	Actor (human/agent/system/service) that asserted the row
`prov:generatedAtTime`	`system_from` timestamp

RDF-star reified triples (per-triple provenance) require spargebra and are deferred.

Configuration

None required. /sparql is enabled on every deployment profile (free, server, cluster) when RELATA_PROFILE is set. Auth is mandatory on server/cluster and optional on free, identical to /query.

SPARQL#

Endpoint#

GET#

POST#

Authentication#

Response format#

Supported subset#

RDF / PROV-O predicates#

Configuration#

See also#