Compatibility, validation & interop
Stable .rete file compatibility
Format 0x08 (generation 2, the dictionary order)
Every writer now writes format byte 0x08 (SPEC §4.11):
0x07 with the dictionary's terms in the SPARQL order instead of byte order
(SPEC §5.2): blank nodes, then IRIs by
their text (so <…/Ng8> sorts before <…/Ng8130_provenance>, which byte order
reverses), then literals, text literals by lexical form. An id then compares as the
term does, within a section and outside the typed literals, so an ORDER BY over a
variable sorts on ids and decodes only the rows it shows. The reader reads 0x05,
0x06, 0x07 and 0x08; readers up to 0.6.1 cannot read 0x08: they refuse it by
name (unsupported .rete format 0x08; this Rete build reads 0x05..=0x07).
- Convert, do not rebuild, but it is a re-encode. Every term gets a new id, so
rete convert in.rete -o out.reteno longer copies the payload of a0x05,0x06or0x07file: it walks the statements and writes them again through the memory-bounded builder (dictionary sorted, every index, the quad orders, the label and text indexes, the schema and the class clusters rebuilt for the new ids; the card, its annex and the build record kept). It runs inside--memory-budget-mb(default 2048) and spills into--tmp-dir; a source's community pyramid is written as it is. Converting a0x08file again gives the same bytes. - The dictionary is about the same size (the OpenCitations sample's goes from 26.16 to 26.03 MB), and the file is not larger: its permutations come out a little smaller because ids that sort together are now adjacent.
- Derived IRIs are found by the writer and refused by name.
rete buildandrete convertlook for IRIs the file's own triples spell out, and when they remove at least 5% of the file they drop the stored text (SPEC §5.3;--no-derive-iristurns it off). The file sets header flag bit5, and a reader that does not know the flag refuses it (unsupported .rete feature); the one-requestRete::query_rangedrefuses it too, since it holds no index. Every other reader (the CLI,sparql-url, the browser) reads it. Most files are not derived (nothing in them reaches 5%), and the dictionary a derived one holds is not complete text: tools that read dictionary chunks themselves must go through the reader. - No backward compatibility is promised before 1.0.0; the catalog is converted in
step with the readers, and the
0x06and0x07readers go once it is. - Publish after the readers, as for
0x06and0x07: a catalog file is converted only when every engine that reads it (the CLI, the clients, the browser engines, the MCPB bundle) is on this release.
Format 0x07 (generation 2, second step)
Every writer now writes format byte 0x07 (SPEC §4.10):
0x06 plus the label index's root node in a cold section of its own (the root
of a big file shrinks by its 37 to 47 KB), an optional card annex for card
fields over the 8 KiB hot cap, and a new set of quad orders for named graphs:
GSPO, SPOG, POSG and OSPG (SPEC §6.5), declared by the root and independent of
--permutations. Readers of this release read 0x05, 0x06 and
0x07; readers up to 0.5.6 cannot read 0x07: they refuse it by name
(unsupported .rete format 0x07; this Rete build reads 0x05..=0x06).
- Convert, do not rebuild.
rete convert in.rete -o out.reteturns a0x05or a0x06file into0x07: the payload is copied, the label root is moved out of the root and the card is kept, with no annex unless a field of it is over the cap. A file with named graphs gets SPOG, POSG and OSPG derived from its GSPO tiles by a sort pass (external past 100 M quads,--tmp-dir), and loses its other graph-leading orders: the nanopub dump goes from 3.88 to 2.51 GB in 75 s.- No backward compatibility is promised before 1.0.0; the catalog is converted in step with the readers, and the0x06reader goes once it is. - Publish after the readers, as for
0x06.
Format 0x06 (generation 2)
Every writer now writes format byte 0x06, generation 2 (SPEC §4):
a 128-byte header, a root block and the Dataset Card at the front of the file,
inside the first 128 KiB a reader fetches, and the data after them. Readers of
this release read both generations; readers up to 0.4.2 cannot read 0x06.
They refuse it by name (unsupported .rete format 0x06; this Rete build reads 0x05..=0x05), never misread it.
- Convert, do not rebuild.
rete convert in.rete -o out.reteturns a0x05file into0x06from its sections: payload copied, never re-parsed. A file whose only labels are the pyramid's legacy label block gains the label indexbuild --label-indexwrites (--no-label-indexskips it); a file with per-graph named graphs is re-encoded as a quad index. - Identity. The content hash of a converted file is the content hash a
fresh build of the same data writes. It is not the
0x05file's hash: the generation is part of the identity. - Publish after the readers. Convert a published dataset only once the readers that fetch it (playground, MCPB, the Python and JS packages) run this release.
0x05stays readable until the catalog is converted.
Format 0x05 (generation 1)
Format byte 0x05 is stable format generation 1, frozen on 2026-07-14 and
first released in Rete 0.3.0. Files carrying the experimental generations
0x01–0x04 predate that freeze and must be rebuilt from RDF source.
Readers from 0.3.0 onward recognize 0x05, but recognition does not guarantee
support for every feature written by a newer release. The exceptions below
include rejected layouts and an older split-group reader that returned
incomplete results. Use a current reader and check the file's build features.
No backwards-compatibility promise before 1.0.0. rete reserves the right to change the
.reteformat while it is pre-1.0, including in ways that require rebuilding a file you have already published.0x05has not moved since it froze on 2026-07-14 — that is a track record, not a guarantee. Keep the RDF source you built from; the durable compatibility promise starts at 1.0.0.
The generation number is not a release version. There is no Rete 1.0.0: the workspace remains 0.x, and the file format froze earlier and independently of any release version (release.md). Two consequences worth stating, because both have bitten:
0x05does not pin reader capability. Nine days after the freeze, #68 changed what the writer emits within0x05— a single index group larger than the tile budget is now split across consecutive tiles — with no generation bump, because the reader change was backward compatible in one direction only. A reader older than #68 returns silently incomplete results on a file that contains split groups, which is #124. "It's0x05" therefore means "the layout is generation 1", not "any generation-1 reader is safe"; read published files with a current reader, and rebuild every bundled engine (playground WASM, the single-file explorer pages, the clients) before publishing a file written by a newer writer.- A
min_reader_versionbyte would have said that in the file, and cannot be retrofitted into0x05. It is item B of #206, the standing survey of what a future generation break should batch together.
--permutations 3: a 0x05 file older readers refuse
rete build --permutations 3 writes SPO, POS and OSP and omits the three
merge-join orders (SOP, PSO, OPS). The default is six and this section is the
reason to think before changing it.
The file is still format 0x05 — no layout moved, no section was added, the
header's byte 50 simply carries the permutation mask instead of zero. A reader
that knows the mask answers every query on it with the same rows, from the same
tiles, as it would on the six-permutation twin. A reader that predates the mask
refuses it:
$ rete stats three.rete # a Rete built before the mask existed
Error: malformed container: expected 6 permutation sections
$ echo $?
1
$ rete sparql-url http://…/three.rete 'SELECT ?s ?p ?o WHERE { ?s ?p ?o }'
Error: malformed container: unexpected container section count
$ echo $?
1
Both the resident decoder and the ranged one check the index container's section
count before reading a payload, so the refusal is the same on a local file, a
lazily range-read one, and every *-url command. rete info, rete verify and
rete card-url still succeed, because they read only the header and the metadata
section and never claim to have read the index.
Guarantee. A reader that does not understand the permutation mask never returns a row from a file that carries fewer than six permutations. Nothing is written empty: a lean file's index container holds three sections, not six, and both decoders compare that count against the six they expect before touching a payload. Verified by reading a 3-permutation file with an unmodified
retebuilt from the previousmain:stats,sparql,export,why,query-url,sparql-url,costand a forced-resident open (RETE_LOCAL_LAZY_ABOVE_MB=0) each printed one of the two errors above and exited 1. That is what makes--permutations 3safe to ship without a format-generation bump. (A current reader accepts the file; it compares the section count against the header's mask instead, and saysindex container section count does not match the header permutation maskif they disagree.)
That is the good failure — loud, immediate, non-zero exit — and it is the
opposite of #124, where a stale
reader returned 65,384 rows where 508,116 were correct. It is not forward
compatibility: a lean file cannot be published to a fleet of older readers and
be expected to work. Keep the default for anything published, and treat
--permutations 3 as a choice about a specific consumer that you control.
Which set a file carries is visible without downloading it: rete info, rete stats and the Dataset Card's signals.permutations all report it, derived from
the header byte rather than stored — see dataset-cards.md.
LABEL_INDEX and SCHEMA (kinds 8, 9): optional sections older readers skip
Since 0.4.0 rete build writes the labels and the schema in sections of their
own (SPEC §6.4, §7.5), and its pyramid-meta carries only the community summary.
The file is still format 0x05: the two kinds are new directory entries, laid out
after every other section, which is exactly the extension the 1 KiB directory was
designed for.
| file built by ≤ 0.3.x | file built by 0.4.0 | |
|---|---|---|
| reader ≤ 0.3.x | unchanged | opens, queries and verifies it. Kinds 8 and 9 are unknown entries: kept verbatim, shifted on every header rewrite, never read. Same rows for every query; but rete search <prefix>, rete summary's schema levels and the planner's measured selectivities come back empty, because the pyramid-meta no longer holds them |
| reader 0.4.0 | reads the labels and schema from the pyramid-meta, as before | reads them from kinds 8 and 9 |
Both sections are outside the content hash. That is what keeps an older
rete verify passing: it hashes the kinds it knows, and a hashed kind 8 or 9 would
make it call every new file corrupt. Each section starts with its own 16-byte
BLAKE3 digest instead, which the current verify checks too. The content hash is
therefore the same for a file with and without them — two builds of the same data
that differ only in --label-index share one identity (and one playground session
cache key), and answer every SPARQL query identically.
Verified against the released 0.3.7 binary (ghcr.io/caviri/rete-cli:0.3.7) on
files with both sections: info, verify, stats, sparql, export and
search all succeed (the last finds nothing, as the table says). Rebuild the
bundled engines before publishing files written by 0.4.0, as for every writer
change.
A text index of some predicates: a section older readers do not see
rete build --text-index --text-index-include/--text-index-exclude <IRI>
(0.4.0) indexes the literals of some predicates only. Readers older than 0.4.0
use any text index they find to prune FILTER(CONTAINS(…)), as if it covered
every literal of the default graph; with an index that left a predicate out,
they would drop that predicate's matching rows without a word. So such an index
is written as section kind 11 rather than 6, with the same payload behind a
16-byte self-digest
(SPEC §6.3). An older
reader keeps the unknown entry and never opens it: the file reads normally,
CONTAINS scans and returns every row, and rete search --contains reports
that the file has no text index. A current reader opens either kind and prunes
only where the index covers the query.
Kind 11 is outside the content hash, like kinds 8 and 9, and its digest is
what a current verify checks. An older verify hashes only the kinds it
knows, so a hashed kind 11 would make it report every such file as corrupt.
Verified against the released 0.3.7 binary (ghcr.io/caviri/rete-cli:0.3.7) on
a --text-index-exclude file: verify says "content hash matches", and info,
sparql and search work (the last finds no text index, as above). The rule
for 0.4.0: a new section kind never makes an older verify call a valid file
corrupt.
The other scope change stays kind 6. --text-index-graphs all adds the named
graphs' literals, so the index covers everything an older reader assumes it
covers, plus more. Its extra candidates are re-checked by the filter and fall
away. It also sets header flag bit 4, which tells a current reader, from the
header alone, that a CONTAINS inside GRAPH or under FROM may use the
index; older readers ignore the bit. A default-scope index (no scope flags) is
the same bytes as before 0.4.0.
Named graphs in the quad index
rete build --named-graphs quad (0.4.0) stores the named graphs in the quad
index (SPEC.md §6.5,
section kind 10) instead of one container per graph (kind 5). It is still format
0x05, and it is refused by every Rete before 0.4.0 — on purpose.
The hazard it is built against: a reader that predates kind 10 keeps it as an
unknown section and ignores it, and ignores header flag bit 3 too (no released
reader checks flag bits). On its own, such a file would open in an old reader
as a file without named graphs: GRAPH queries would return nothing and
export would drop every named-graph quad, without an error. So the writer
also appends a seal section to the default-graph index container, and every
released reader checks that container's section count before it reads a single
payload — the same check that refuses a --permutations 3 file:
$ rete sparql quad.rete 'SELECT * { GRAPH ?g { ?s ?p ?o } } LIMIT 1' # rete 0.3.7
Error: malformed container: index container section count does not match the header permutation mask
$ rete sparql-url http://…/quad.rete '…' # rete 0.3.7
Error: malformed container: unexpected container section count
| Reader | info, verify, card-url | every query, export, stats, lazy or remote open |
|---|---|---|
| 0.3.0 – 0.3.3 (expect exactly 6 sections) | work; verify says OK | refused: 7 or 4 sections |
| 0.3.4 – 0.3.7 (expect the mask's 3 or 6) | work; verify says OK | refused: 7 or 4 sections |
| 0.4.0 | work; verify also checks the quad index | read |
Checked with the 0.3.7 and 0.3.5 binaries and with 0.3.0 built from its tag, on
the OpenCitations sample: none of them returned a row or a quad from any
command; 0.3.0 says malformed container: expected 6 permutation sections.
- Why not a new format byte: the refusal comes from a check every
0x05reader already performs, it leaves the header-only tools (info,card-url, the catalog survey) working on these files, and it does not spend a generation number on one feature — a generation break is meant to batch several (#206). - Why the old
verifystays truthful: the content hash keeps its part list; the seal, inside the hashed container, carries the quad section's digest. An old reader verifies everything it can read; a new one also checks the quad index against the seal. So the quad index is hashed by reference: unlike the self-digested kinds 8, 9 and 11, it stays part of the file's content hash. - The quad index is written only with three or six permutations (
perms + 1is then 4 or 7, never what an old reader wants). - A file without named graphs is byte-identical whichever layout was asked for, so the flag is harmless on triple-only inputs.
Like --permutations 3, this is not forward compatibility: publish a
quad-index file only where every reader is 0.4.0 or later (the playground, the
explorer pages and the clients are rebuilt in the release that reads it). Files
already published with the per-graph layout keep working with every reader.
0.4 writer changes that every 0x05 reader reads
Four writer choices moved or became flags in 0.4 (cli.md,
measurements in BENCHMARK.md). None of them changes the
layout, so unlike --permutations 3 they need no reader update:
- Single-segment zstd frames (the new default). Each tile and chunk now records
its content size, which lets zstd pick its small-input parameters: at the same
level the four measured datasets came out 0.7–7.0% smaller. Older writers' streaming frames still
read, and
RETE_ZSTD_FRAME=streamreproduces a 0.3 file byte for byte. --tile-kib/--dict-chunk-kib. Tiles and chunks are routed by their directories, so any size reads.--zstd-level. Any level decodes with the same decoders.--frequent-objects N(off by default) puts frequent object-only terms in the shared dictionary section (SPEC §5); readers have always looked terms up there first.
Verified by reading files written with the new defaults and with
--frequent-objects 64 with the released 0.3.5 and 0.3.7 binaries: verify
passes and the 12-query OpenCitations set returns the same rows as the new reader,
over the lazy local open. The browser reader decodes the new frames with the same
ruzstd it ships.
The 0.4 build record
The build-info section (kind 7) carries much more in 0.4.0 — engine, inputs,
counts, timings (Dataset Cards)
— all as new optional JSON fields, and the JSON may be followed by spaces up to
the section's length (the record is reserved before the build ends and filled
in place). Both are invisible to older readers: verified with the released
0.3.7 binary on the OpenCitations development sample built both ways, card
prints its known subset with no warning and verify passes (the section is
outside the content hash).
The 0.5 build record
From 0.5.0 every writer writes format 0x06 and a build record: the CLI
with or without a card, rete merge, the Python, R and Java clients and the
browser engine. The record gains a front_end field (cli, python, r,
java, wasm), optional like the rest. A client's or the browser's record
is the lean one (engine, host, options, the input's length and BLAKE3, counts);
only the CLI measures phases, spill and starter-query costs. A file with no card
gets a card region that is its record and nothing more (no doubling, no 8 KiB of
slack: the region is in the first read), so rete recard --in-place of such a
file copies it once; a file written with a card keeps the room to re-card in
place. Two builds of one
input differ in the record by design, so byte comparison of builds is done on
the file without it (rete_core::attach_build_info(image, &[])) or with
RETE_BUILD_RECORD=reproducible.
A card after the data
In 0x05, the memory-bounded build, rete merge and rete recard --in-place
wrote the Dataset Card (and the build record beside it) after every other
section instead of between the header and the dictionary
(SPEC §4.9). In 0x06 the card
has one place, the card region at the front.
Nothing about the format changes: the header has always been the directory,
every reader has always located the card through it, and the content hash folds
the card first wherever it lies — the same card on the same data hashes the same
in either place. A file re-carded in place also keeps its old card, build record
and footer as bytes no section points at, which every reader ignores.
Verified on a carded fixture (default graph, a named graph, --label-index,
--text-index) written both ways and re-carded in place, with the released
0.3.7 and 0.4.0 CLIs (verify, card, sparql, and card-url against an
nginx range server: the same 3–4 range requests as a card at the front), and the
0.4.0 rete-graph Python and JavaScript packages, each opening the files locally
and over HTTP: same card, same rows, same content hash.
Is it compatible with RDF?
Yes — rete is RDF. It is not a new graph model; it's a storage + query
format for RDF, built on the standard Rust RDF stack
(oxrdf,
oxttl,
spargebra).
It implements the RDF 1.1 data model:
| RDF concept | Support |
|---|---|
| IRIs | ✅ |
| Literals (plain) | ✅ |
Typed literals ("30"^^xsd:integer) | ✅ — datatype preserved |
Language-tagged literals ("hi"@en) | ✅ — tag preserved |
| Blank nodes | ✅ (as terms; non-distinguished variables in patterns) |
| Named graphs / RDF datasets | ✅ — N-Quads in, GRAPH/FROM/FROM NAMED in SPARQL |
| SPARQL 1.1 query | ✅ — see SPARQL support |
| SHACL Core validation | ✅ — see SHACL validation |
Input formats: N-Triples (.nt), N-Quads (.nq), Turtle (.ttl), and
RDF/XML (.rdf / .owl / .rdfxml).
Output: N-Quads (rete export, lossless round-trip), Turtle and expanded
JSON-LD (rete export --format ttl|jsonld, default graph only), and SPARQL
Results JSON (rete sparql --json).
Interop in practice: anything that emits N-Triples/N-Quads/Turtle/RDF-XML can
feed rete build, and rete export round-trips back to N-Quads for any other RDF
tool. So rete slots in as a publishing + query layer next to your existing RDF
pipeline.
OWL: OWL is a language, not a file format — an ontology is a set of RDF
triples that can be serialized several ways. The two common RDF serializations,
Turtle and RDF/XML, both ingest directly (.ttl, .rdf/.owl), so most
published OWL ontologies build with no conversion. The non-RDF serializations —
OWL/XML (functional XML) and OWL Functional Syntax — are not RDF, so
convert them to RDF first (e.g. owlready2, robot convert, or Protégé "Save
as → RDF/XML"). Once ingested, OWL axioms are just triples you can query; to
materialize OWL RL / RDFS entailments see Reasoning
(rete build --reason / rete reason).
RDF-star & RDF 1.2 — both, and selectable. rete ingests, stores, and queries quoted triples — statements about statements — with the SPARQL-star patterns and built-ins (see SPARQL support). Both surfaces are first-class in both directions, chosen by one flag that spells the same in each:
RDF-star << s p o >> | RDF 1.2 <<( s p o )>> | |
|---|---|---|
| N-Triples / N-Quads in | yes | yes (always — that reader is rete's own) |
| Turtle / TriG in | rete build --quoted-triple-syntax rdf-star (default) | --quoted-triple-syntax rdf12 |
| N-Quads / Turtle / TriG out | rete export --quoted-triple-syntax rdf-star | --quoted-triple-syntax rdf12 (default) |
| SPARQL query | << s p o >>: a quoted triple, unless the query declares VERSION "1.2" | <<( s p o )>>: a triple term, always; under VERSION "1.2", << s p o >> is a reified triple (?r rdf:reifies <<( s p o )>>) |
The two input defaults look inconsistent and are not: <<( … )>> is
unambiguous, so reading an RDF 1.2 file as RDF-star fails loudly, whereas
reading an RDF-star file as RDF 1.2 succeeds with a different graph. The
export default optimises for who can read the dump; the input default optimises
for not silently changing what a file means. Composing the two makes rete a
translator between the RDF-star and RDF 1.2 worlds — see
Triple-store interop.
RDF 1.2 reification is supported on input, and needed no storage change:
under --quoted-triple-syntax rdf12 the Turtle/TriG reader takes rdf:reifies,
the << s p o >> reifier form and Turtle-1.2 annotation syntax
({| … |}), all of which expand to ordinary statements — a blank node, an IRI
and a term — that rete has always stored and SPARQL has always queried. rete's
term model turned out to be a superset of both standards; only the parse
boundary differed. (rete's own writers emit triple terms, not reification:
an exported quoted triple comes back as <<( s p o )>>, not as
_:r rdf:reifies ….)
Base-direction language strings ("…"@lang--dir, RDF 1.2's
rdf:dirLangString) are modelled — DATATYPE reports rdf:dirLangString and
LANG returns the language subtag — and a leading SPARQL 1.2 VERSION "1.2"
declaration is accepted (it switches << … >> in the query to the SPARQL 1.2
reified triple; see SPARQL 1.2 triple terms); --quoted-triple-syntax rdf12 is also what lets the
Turtle reader parse the @lang--dir form. Not yet: the new SPARQL 1.2
direction functions (LANGDIR…). The RDF 1.2 Turtle/TriG reader runs in the
browser too: the in-browser builder's Quoted triples: RDF 1.2 choice reads
it, beside RDF-star Turtle/TriG and both N-Triples/N-Quads surfaces.
Current limits (not RDF-incompatible, just unimplemented): OWL/XML and
Functional Syntax need an external convert-to-RDF step (above); and there is no
in-place SPARQL Update — the file is immutable by design, though
rete serve runs a live endpoint that accepts SPARQL Update into a
journal beside the untouched base file. Turtle/JSON-LD export covers the default
graph only (use N-Quads export for named graphs).
Validation
There are five independent ways to check correctness:
-
Syntactic —
rete validate. Parses N-Triples/N-Quads/Turtle without building, and fails with a precise line/column error on malformed input:rete validate data.ttl # valid: 4210 statement(s) — 4180 in the default graph, 2 named graph(s) rete validate broken.ttl # Error: broken.ttl: Parser error at line 12 ... not a valid subjectrete buildruns the same parse, so a successful build is also a validation. -
Shape validation —
rete shacl. Validates a.retegraph against SHACL Core shapes read from Turtle. It exits non-zero when the validation report is non-conformant, so it works as a CI gate. See SHACL validation for the supported target, path, and constraint components.rete shacl data.rete --shapes shapes.ttl rete shacl data.rete --shapes shapes.ttl --format json -
Integrity —
rete verify. Recomputes the blake3 content hash and compares it to the header, detecting any corruption or truncation of a.retefile. -
Round-trip —
rete export. Dumps back to N-Quads; diff against the source (or re-validate the output) to confirm nothing was lost. -
Logical coherence —
rete reason. A prototype OWL RL / RDFS reasoner materializes RDFS/OWL entailments and flags incoherent points — logical contradictions such as disjoint-class violations,sameAs/differentFromclashes, functional-property conflicts, andowl:Nothingmembership. It exits non-zero on incoherence, so it doubles as a CI coherence gate. See Reasoning & coherence for the full rule set and scope (it is a documented subset, not full OWL DL).rete reason data.rete # inferred 9 new triple(s) # 1 inconsistency(ies) found: # [disjoint-classes] <http://ex/p> is typed as both … owl:disjointWith
rete shacl is SHACL Core support, not the whole shape-language universe:
SHACL-SPARQL, SHACL-AF, JavaScript extensions, SHACL 1.2 draft features, and ShEx
are not implemented.
Could it speak Cypher too?
rete cypher provides a read-only prototype that translates a small Cypher
subset to SPARQL. It is not full openCypher, and the data models differ.
Cypher targets the labeled property graph (LPG) model (Neo4j): nodes and
relationships both carry a label and arbitrary key/value properties. RDF is a
triple model: everything is (subject, predicate, object). They overlap a
lot, but not perfectly:
| Cypher (LPG) | RDF / SPARQL equivalent |
|---|---|
(a:Person) (node label) | ?a rdf:type ex:Person |
(a)-[:KNOWS]->(b) | ?a ex:knows ?b (a triple / BGP) |
(a)-[:KNOWS*]->(b) (var-length) | ?a ex:knows+ ?b (property path) |
node property a.age | ?a ex:age ?age (triple with a literal) |
relationship property [:KNOWS {since: 2020}] | no direct triple — needs reification or RDF-star |
RETURN, WHERE, LIMIT | SELECT, FILTER, LIMIT |
So a "loose Cypher" front-end — read-only MATCH … WHERE … RETURN, including
variable-length relationships — maps cleanly onto the BGP + property-path + filter
machinery this engine already has. The genuine gaps are LPG features with no plain
RDF triple: relationship properties, and the distinction between a node label
and a node property. Those need a modeling convention (reification, or RDF-star
once supported).
What this is not: full openCypher (no writes/CREATE/MERGE, no APOC,
no stored procedures) — the file is immutable and server-less by design.
Status: available as a prototype via rete cypher. It is a translation
layer, not a second engine: a small Cypher subset is parsed into an AST, emitted
as an equivalent SPARQL SELECT string, and evaluated by the existing SPARQL
engine — so it reuses the same BGP/join, property-path, and FILTER machinery.
Supported subset (read-only)
query := MATCH patterns [WHERE conditions] RETURN items [LIMIT n]
patterns := pattern ("," pattern)*
pattern := node (rel node)*
node := "(" [var] [":" Label] ")"
rel := "-" "[" ":" REL ["*"] "]" "->" (forward)
| "<-" "[" ":" REL ["*"] "]" "-" (reverse)
conditions := condition (("AND" | "OR") condition)*
condition := var "." prop OP value (property comparison)
| var "=" value (node identity)
OP := "=" | "<>" | "!=" | "<" | "<=" | ">" | ">="
value := number | "string" | <iri>
items := item ("," item)*
item := var | var "." prop
Variable-length -[:REL*]-> lowers to the SPARQL property path REL+
(one-or-more) for the prototype; bounded forms (*N..M) are not supported.
Name → IRI convention
A bare label/relationship/property name X maps to <BASE + X>, where BASE
defaults to http://ex/ and is overridable with --base. With the default base:
| Cypher | Emitted SPARQL |
|---|---|
(a:Library) | ?a a <http://ex/Library> |
-[:dependsOn]-> | predicate <http://ex/dependsOn> |
a.name | ?a <http://ex/name> ?a_name |
(a)-[:dependsOn*]->(b) | ?a <http://ex/dependsOn>+ ?b |
Out of scope (rejected with a clear error, never a panic)
Writes (CREATE / MERGE / SET / DELETE), OPTIONAL MATCH, WITH,
aggregations, RETURN *, relationship variables/properties
([r:REL {since: 2020}]), and multiple labels per node. These genuinely depend
on LPG features (relationship properties) or write/aggregation semantics outside
this prototype's scope.
Worked example
Against the bundled examples/deps.nt dependency graph:
rete build examples/deps.nt -o deps.rete
# Which packages transitively depend on the vulnerable log4x?
rete cypher deps.rete \
"MATCH (a)-[:dependsOn*]->(b) WHERE b = <http://ex/log4x> RETURN a"
# ?a=<http://ex/app>
# ?a=<http://ex/web>
# ?a=<http://ex/auth>
# ?a=<http://ex/logging>
That query is translated to
SELECT ?a WHERE { ?a <http://ex/dependsOn>+ ?b . FILTER(?b = <http://ex/log4x>) }
and evaluated by the SPARQL engine's property-path machinery.