SPARQL / RDF triplestores

Stardog, Apache Jena Fuseki, Blazegraph, Ontotext GraphDB, OpenLink Virtuoso and
AllegroGraph are all RDF triplestores that speak the SPARQL 1.1 Protocol over
HTTP. Until now the only way to use them from this library was to hand-write
SPARQL and pass it to store.query(...).

SparqlGraphDialect (src/graph/sparql) implements the same
graph dialect contract as the Cypher, Gremlin and Dgraph
DQL dialects — the same 13 compile* methods, the same findAll-shaped spec
objects — and compiles them to SPARQL. Every one of the six stores now exposes a
graph() accessor that returns a dialect bound to it:

import { Op } from 'ts-prorm-orm';
import { FusekiStore } from 'ts-prorm-orm/nosql/fuseki';

const store = new FusekiStore({ endpoint: 'http://localhost:3030', dataset: 'kb' });
await store.connect();

const graph = store.graph();

await graph.createNode('User', { id: 42, name: 'Ada', age: 36 });

const users = await graph.findNodes({
  label: 'User',
  attributes: ['id', 'name', 'age'],
  where: { age: { [Op.gte]: 30 } },
  order: [['name', 'ASC']],
  limit: 10,
});

await graph.relate({
  fromLabel: 'User',  fromWhere: { id: 42 },
  edgeLabel: 'HAS_POSTS',
  toLabel: 'Post',    toWhere: { id: 7 },
});

const reachable = await graph.traverse({
  label: 'User', where: { id: 42 },
  edgeLabel: 'KNOWS', direction: 'both', maxDepth: 3,
});

The raw query / update / ask / add / drop methods on each store are
untouched. They are a legitimate escape hatch for the things SPARQL does that no
ORM shape covers — CONSTRUCT, federation, inference, vendor extensions. They are
simply no longer the only way in.

Side by side

The graph() calls from the top of this page and the SPARQL each one compiles to, with the default http://prorm.dev/ns/ bases. ?_p0-style placeholders are filled by bindSparql() just before the request is sent (see Injection).

import { Op } from 'ts-prorm-orm';
import { FusekiStore } from 'ts-prorm-orm/nosql/fuseki';

const store = new FusekiStore({ endpoint: 'http://localhost:3030', dataset: 'kb' });
await store.connect();
const graph = store.graph();

// 1. flat projection: attributes are known, one row per node
const users = await graph.findNodes({
  label: 'User',
  attributes: ['id', 'name', 'age'],
  where: { age: { [Op.gte]: 30 } },
  order: [['name', 'ASC']],
  limit: 10,
});

// 2. everyone within two KNOWS hops, either direction
const circle = await graph.traverse({ label: 'User', where: { id: 42 }, edgeLabel: 'KNOWS', direction: 'both', maxDepth: 2 });

// 3. update one property
await graph.updateNodes('User', { id: 42 }, { age: 37 });

// 4. an edge between two matched nodes
await graph.relate({ fromLabel: 'User', fromWhere: { id: 42 }, edgeLabel: 'HAS_POSTS', toLabel: 'Post', toWhere: { id: 7 } });

// 5. delete a node and every triple pointing at it
await graph.destroyNodes('User', { id: 42 });

# 1.  ?_p0 = 30
SELECT ?s ?v_id ?v_name ?v_age
WHERE {
  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?s <http://prorm.dev/ns/prop/age> ?v_age . }
  OPTIONAL { ?s <http://prorm.dev/ns/prop/id> ?v_id . }
  OPTIONAL { ?s <http://prorm.dev/ns/prop/name> ?v_name . }
  FILTER(?v_age >= ?_p0)
}
ORDER BY ASC(?v_name)
LIMIT 10

# 2.  ?_p0 = 42
SELECT DISTINCT ?t
WHERE {
  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?s <http://prorm.dev/ns/prop/id> ?v_id . }
  FILTER(?v_id = ?_p0)
  { ?s (<http://prorm.dev/ns/edge/KNOWS>|^<http://prorm.dev/ns/edge/KNOWS>) ?t . }
  UNION { ?s (<http://prorm.dev/ns/edge/KNOWS>|^<http://prorm.dev/ns/edge/KNOWS>)/(<http://prorm.dev/ns/edge/KNOWS>|^<http://prorm.dev/ns/edge/KNOWS>) ?t . }
}

# 3.  ?_p0 = 42, ?_p1 = 37
DELETE { ?s <http://prorm.dev/ns/prop/age> ?old_age . }
INSERT { ?s <http://prorm.dev/ns/prop/age> ?_p1 . }
WHERE {
  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?s <http://prorm.dev/ns/prop/id> ?v_id . }
  FILTER(?v_id = ?_p0)
  OPTIONAL { ?s <http://prorm.dev/ns/prop/age> ?old_age . }
}

# 4.  ?_p0 = 42, ?_p1 = 7
INSERT { ?a <http://prorm.dev/ns/edge/HAS_POSTS> ?b . }
WHERE {
  ?a <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?a <http://prorm.dev/ns/prop/id> ?v_id . }
  FILTER(?v_id = ?_p0)
  ?b <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/Post> .
  OPTIONAL { ?b <http://prorm.dev/ns/prop/id> ?v_id_1 . }
  FILTER(?v_id_1 = ?_p1)
}

# 5.  two operations in one request: incoming triples, then the node's own
DELETE { ?src ?inp ?s . }
WHERE {
  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?s <http://prorm.dev/ns/prop/id> ?v_id . }
  FILTER(?v_id = ?_p0)
  ?src ?inp ?s .
} ;
DELETE { ?s ?p ?o . }
WHERE {
  ?s <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  OPTIONAL { ?s <http://prorm.dev/ns/prop/id> ?v_id . }
  FILTER(?v_id = ?_p1)
  ?s ?p ?o .
}

The triple-mapping convention

RDF has no labels, no properties and no edges — only triples. Any mapping from a
property graph onto RDF has to be invented, and the failure mode of an implicit
convention is that two systems write the same data under different IRIs and
neither can read the other's. So here it is, in full:

ORM concept	RDF	Default IRI
node label `User`	an `rdfs:Class`-style class IRI	`<http://prorm.dev/ns/class/User>`
the label itself	`<subject> rdf:type <class IRI>`	—
node with `id` 42	the subject IRI	`<http://prorm.dev/ns/data/User/42>`
property `name`	a predicate IRI	`<http://prorm.dev/ns/prop/name>`
property value `'Ada'`	an object literal	`"Ada"`
edge label `HAS_POSTS`	a predicate IRI	`<http://prorm.dev/ns/edge/HAS_POSTS>`
an edge	`<…/data/User/42> <…/edge/HAS_POSTS> <…/data/Post/7>`	—

The same data drawn both ways: one node with two properties and an edge, and the triples it becomes (IRIs shortened to their last segment):

So User.create({ id: 42, name: 'Ada' }) becomes:

INSERT DATA {
  <http://prorm.dev/ns/data/User/42> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://prorm.dev/ns/class/User> .
  <http://prorm.dev/ns/data/User/42> <http://prorm.dev/ns/prop/id>   "42"^^<http://www.w3.org/2001/XMLSchema#integer> .
  <http://prorm.dev/ns/data/User/42> <http://prorm.dev/ns/prop/name> "Ada" .
}

Configuring it

Nothing above is hard-coded. Every base can be replaced, and individual names
can be pinned onto an existing vocabulary:

const graph = store.graph({
  base: 'https://example.org/kb',        // moves all four bases at once
  // …or set them individually:
  classBase:    'https://example.org/kb/class/',
  propertyBase: 'http://xmlns.com/foaf/0.1/',
  edgeBase:     'https://example.org/kb/rel/',
  dataBase:     'https://example.org/kb/id/',

  classIris:    { User: 'http://xmlns.com/foaf/0.1/Person' },
  propertyIris: { name: 'http://xmlns.com/foaf/0.1/name' },
  edgeIris:     { HAS_POSTS: 'http://schema.org/author' },

  idProperty: 'uid',        // which attribute is the node's identity
  graph: 'urn:graph:main',  // scope every pattern and write to a named graph
  defaultLanguage: 'en',    // tag bare string literals
});

Set them once at construction instead, and store.graph() picks them up:

new FusekiStore({ dataset: 'kb', graphMapping: { base: 'https://example.org/kb' } });

Why these choices

Full IRIs, never prefixed names. Everything is emitted as an absolute IRI
inside <…>. A prefixed name's local part has to satisfy the PN_LOCAL
grammar, which plenty of real attribute names violate (first name,
2fa_enabled, price$); emitting one anyway is either a parse error at the
server or, worse, a different IRI than intended. An absolute IRI has one rule
to get right instead of two.

Identity is an IRI derived from the id, not a blank node. A blank node has
no name outside the result set it appeared in — you cannot come back and
UPDATE, DELETE or link to one. Since a node's IRI is a pure function of its
label and its id, the subject is known before a request runs, which is exactly
what makes upsert and delete expressible without a lookup. The cost: changing
an id is a delete plus a create, not an update. Blank nodes read back fine;
they are just not something this dialect writes.

IRI segments are percent-encoded, not safeIdent-ed. The Cypher and Gremlin
dialects sanitize identifiers with safeIdent, which maps everything outside
[A-Za-z0-9_] to _. That is not injective, so labels Book/Chapter and
Book_Chapter would collapse onto one class IRI and silently share storage.
Percent-encoding round-trips. (safeIdent is still used in this dialect — for
SPARQL variable names, where the grammar really does want that character set.)

A plain JavaScript string is always a literal. To write an IRI you must say
so:

import { iri } from 'ts-prorm-orm/graph/sparql';
await graph.createNode('User', { id: 1, homepage: iri('https://ada.example') });

If "https://…" were auto-detected as an IRI, a homepage attribute holding a
URL string would silently become a link and stop matching the value it was
stored as.

RDF has no null. Setting a property to null or undefined deletes its
triples; there is no "present but empty". A where: { nickname: null } compiles
to !BOUND(?v_nickname).

Properties are multi-valued. Nothing in RDF stops two name triples on one
subject. A match then yields one row per combination — exactly as a SQL join
would — and findNodes folds repeated values into an array. Use distinct: true
and explicit attributes to keep this predictable.

Datatypes

JavaScript	RDF term
`'Ada'`	`"Ada"` (or `"Ada"@en` with `defaultLanguage`)
`36`	`"36"^^xsd:integer`
`1.5`	`"1.5"^^xsd:decimal`
`Infinity` / `NaN`	`"INF"^^xsd:double` / `"NaN"^^xsd:double`
`true`	`"true"^^xsd:boolean`
`new Date(...)`	`"…"^^xsd:dateTime`
`iri('http://…')`	`<http://…>`
`lang('bonjour', 'fr')`	`"bonjour"@fr`
`typed('P1D', xsdDuration)`	`"P1D"^^<…#duration>`

The datatypes are not cosmetic. A number written as a plain "10" literal sorts
and compares as a string, so age > 9 would exclude 10.

Injection: what is escaped, what is validated

SPARQL has no wire-level parameter binding. A SPARQL request is one string;
there is no $p0 the server substitutes for you. (RDF4J and Jena expose
setBinding in their Java APIs, not over HTTP.) So the work is split in two,
and the split is the security boundary:

Compilation never sees a value become text. Every compile* method
returns { text, params } where text contains only ?_p0-style
placeholders. This is a property you can test, and the test suite does:
expect(stmt.text).not.toContain('Ada').

One function turns placeholders into text. bindSparql(text, params) in
src/graph/sparql/terms.ts is the only place a value is serialized, through
serializeTerm, which can only emit a well-formed RDF term. The dialect's
query() calls it immediately before dispatch; nothing else concatenates.

Within that:

Literals are escaped. A lexical form is emitted inside "…" with \,
", LF, CR, TAB, BS and FF replaced by their SPARQL escapes (backslash first,
so the escapes this introduces are not double-escaped). An escaped literal
cannot contain an unescaped ", so it cannot terminate its own quote — which
is the entire injection surface for a literal.

IRIs are validated and rejected, never escaped. <…> has no escape
mechanism for the characters that would break it, so there is nothing to
escape to. An IRI containing <, >, ", {, }, |, ^, `,
\, a space or an ASCII control character throws a ValidationError. That is
exactly the set IRIREF excludes in the SPARQL grammar. An IRI with no scheme
is also rejected.

Language tags are validated against SPARQL's LANGTAG production.

Datatype IRIs go through the same IRI validation.

IRI path segments are percent-encoded first, then the assembled IRI is
validated — encoding makes a hostile label harmless, and the validation
catches a malformed configured base, which is never encoded.

IN binds one placeholder per element. SPARQL's IN takes an expression
list, not a collection value, and the only way to serialize an array into an
expression list is concatenation — which is the thing being avoided.

An unbound placeholder throws. A leftover ?_p3 is a syntactically valid
SPARQL variable, so the server would run the query unconstrained and return
the wrong rows rather than an error.

Labels, property names and edge labels are interpolated, not bound — no
graph language lets you parameterise them — so every compile entry point calls
requireGraphLabel() first. A missing label throws instead of producing
<…/class/undefined>, which is a perfectly good IRI that nothing is stored
under: the query would run, match nothing, and report nothing wrong.

What compiles, and what refuses to

`compile*` method	Compiles to
`compileMatch`	`SELECT` with `OPTIONAL` property bindings + `FILTER`, `ORDER BY`, `LIMIT`/`OFFSET`, `COUNT`, `DISTINCT`, includes as `OPTIONAL` edge hops
`compileCreateNode`	`INSERT DATA`
`compileUpdateNodes`	`DELETE … INSERT … WHERE`
`compileDeleteNodes`	two `DELETE … WHERE` operations in one request
`compileUpsertNode`	`DELETE … WHERE` then `INSERT DATA`, keyed on the identity property
`compileIncrement`	`DELETE … INSERT … WHERE` with `COALESCE(?old, 0)`
`compileCreateEdge`	`INSERT … WHERE` between two matched endpoint sets
`compileTraverse`	property paths — a `UNION` of fixed-length paths, or `+`/`*`
`compileShowLabels`	`SELECT DISTINCT ?label` over the class base
`compileCreateConstraint`	✗ `GraphCapabilityError`
`compileDropConstraint`	✗ `GraphCapabilityError`
`compileCreateIndex`	✗ `GraphCapabilityError`
`compileDropIndex`	✗ `GraphCapabilityError`

Why those four throw

Constraints. RDF has no uniqueness or existence constraints. SHACL and OWL
describe and validate shapes; they are not DDL, they are not universally
supported, and a CREATE CONSTRAINT that silently does not constrain is worse
than an error. Use your store's own validation (Stardog ICV, GraphDB SHACL).

createTable() still works — it registers the node model and its schema hints —
it just does not try to materialize primary keys and unique columns as
constraints the way the Cypher dialect does.

Indexes. A triplestore indexes every triple by construction. Everything
beyond that is vendor-specific and outside SPARQL: Stardog search indexes,
GraphDB Lucene/vector connectors, Virtuoso's RDF_OBJ_FT_RULE_ADD.

Other refusals

Interactive transactions. The SPARQL 1.1 Protocol has no transaction API.
startTransaction() throws. The atomic unit you actually get is one update
request, which may contain several ;-separated operations — which is how
delete and upsert are compiled here.

Upsert on a non-identity key. What makes an upsert work at all is that the
subject IRI is a pure function of the id, so no lookup is needed. On any other
key it would need one, and SPARQL cannot do "find it or mint one" atomically.
A three-operation approximation would look correct and quietly depend on the
store treating one request as one transaction.

Edge properties. A triple has three slots and none is free for
since: 2019. RDF-star quoted triples solve it, but they are not part of
SPARQL 1.1 and a store without them rejects the whole update — so they are
opt-in per store (rdfStar: true). Stardog, Fuseki and GraphDB default to on.

Bounded traversal deeper than 32 hops (configurable via
maxPathExpansion) — see below.

Traversal depth and property paths

SPARQL 1.1 property paths have ^, /, |, *, +, ? and ! — but no
bounded repetition. elt{n,m} was in the working draft and was dropped from
the Recommendation, so emitting <e>{1,3} is a parse error on a conforming
store. A bounded depth is therefore expanded into a UNION of fixed-length
sequence paths, which is exact and portable:

graph.compileTraverse({ label: 'User', edgeLabel: 'KNOWS', maxDepth: 3 })

{ ?s <…/edge/KNOWS> ?t . }
UNION { ?s <…/edge/KNOWS>/<…/edge/KNOWS> ?t . }
UNION { ?s <…/edge/KNOWS>/<…/edge/KNOWS>/<…/edge/KNOWS> ?t . }

maxDepth: Infinity uses + instead (or * when minDepth is 0, or a fixed
prefix followed by + when minDepth > 1). direction: 'in' inverts the path
with ^; 'both' alternates with (<e>|^<e>).

Two projection shapes

RDF does not tell you which properties a subject has, so compileMatch picks
one of two shapes:

Flat — when the attribute list is known (from attributes, or from a node
model registered with defineNode / createTable), each attribute gets its
own projected variable. One row is one node, and ORDER BY/LIMIT mean what
they say. Prefer this.

Open — otherwise, SELECT ?s ?p ?o over a subquery that has already
applied the filter, ordering and slice to the subjects. Without the
subquery, LIMIT 10 would limit triples rather than nodes and return
three-and-a-half users. The order variables are projected out of the subquery
and the ORDER BY repeated outside, because a subquery's ordering is not
guaranteed to survive the outer join.

findNodes() folds either shape back into node objects, each carrying its
subject IRI as $iri.

Why property bindings are `OPTIONAL`

Every where field compiles to OPTIONAL { ?s <prop> ?v_field } plus a
FILTER, never to a plain triple pattern. A plain pattern is a join, and that
would mean:

{ nickname: { [Op.ne]: 'x' } } drops every node with no nickname at all;

Op.isNull can never match, because the pattern binding the variable would
have to exist first;

one leg of an Op.or annihilates the whole solution instead of being false.

OPTIONAL + FILTER reproduces the ORM's three-valued semantics.

Where the six stores differ

All six satisfy the SparqlExecutor interface (query / update / ask plus
the lifecycle), which is how graph() works without the dialect owning any HTTP
of its own. They differ in ways that matter:

Store	Query path	Update path	`rdfStar` default	Notes
Stardog	`/<db>/query`	`/<db>/update`	on	ICV is database-level validation, not SPARQL DDL
Fuseki	`/<ds>/query`	`/<ds>/update`	on	Jena implements RDF-star
GraphDB	`/repositories/<r>`	`/repositories/<r>/statements`	on	full-text/vector indexes are connectors, not `CREATE INDEX`
Blazegraph	`/blazegraph/namespace/<ns>/sparql`	same	off	its `<<…>>` "RDR" predates and differs from RDF-star
Virtuoso	`/sparql`	same	off	commonly anonymous read-only — see below
AllegroGraph	`/repositories/<r>`	same	off	per-triple metadata is triple attributes, not RDF-star

Because three of the six split query and update across two paths, the dialect
classifies every compiled statement by its leading keyword (skipping comments
and PREFIX/BASE headers — without stripping # globally, since # is a
legal and common IRI character) and posts it to the right one. An update sent to
a query path is a 400, not a no-op.

Read-only endpoints

Virtuoso's public /sparql is very often exposed with anonymous read-only
access. Declare it, and an update fails naming the reason instead of coming back
as an opaque SPARQL Request Failed / 37000 permission fault:

const store = new VirtuosoStore({
  endpoint: 'https://dbpedia.org',
  graphMapping: { readOnly: true },
});
await store.graph().createNode('User', { id: 1 });
// GraphCapabilityError: "SPARQL 1.1 Update (endpoint configured read-only)" is
// not supported by the virtuoso graph dialect

Nothing is sent to the server.

Escape hatch

The dialect covers the ORM shape. Anything outside it still goes through the
store directly:

await store.query(`
  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
  SELECT ?name (COUNT(?friend) AS ?n) WHERE {
    ?p foaf:name ?name ; foaf:knows ?friend .
  } GROUP BY ?name HAVING (COUNT(?friend) > 5)
`);

Raw results come back exactly as the endpoint sent them (SPARQL JSON bindings,
unflattened) — that is the point of an escape hatch. The dialect's own
findNodes / query flatten typed literals into JavaScript values.

SPARQL / RDF triplestores

Side by side#

The triple-mapping convention#

Configuring it#

Why these choices#

Datatypes#

Injection: what is escaped, what is validated#

What compiles, and what refuses to#

Why those four throw#

Other refusals#

Traversal depth and property paths#

Two projection shapes#

Why property bindings are OPTIONAL#

Where the six stores differ#

Read-only endpoints#

Escape hatch#

See also#