Getting started
Build a small dependency graph, ask which packages depend on a library, and inspect the description carried inside the file. You need Docker and an empty working directory; no source checkout or Rust installation is needed.
Set up the CLI
Use the installation selector to choose your operating system and package. The Docker route below is a reproducible setup for this example; if you already installed the native CLI, continue at Build a graph.
The published CLI container runs the same commands as a local rete binary.
Define a wrapper in your current shell so that files in your working directory
are available inside the container.
This example pins the published 0.7.5 image, which writes format 0x08 and
reads 0x05 to 0x08. Readers up to 0.6.x cannot open 0x08 files. See
Compatibility before exchanging files with older readers.
On a POSIX shell (Linux or macOS):
alias rete='docker run --rm -i -v "$PWD:/data" -w /data ghcr.io/caviri/rete-cli:0.7.5'
On PowerShell:
function rete { docker run --rm -i -v "${PWD}:/data" -w /data ghcr.io/caviri/rete-cli:0.7.5 @args }
-v shares your directory with /data, -w makes relative filenames work,
and -i allows piped input. Without -i, a piped build can silently receive
empty input and produce an empty graph. On Linux, add
--user "$(id -u):$(id -g)" if output files should belong to your user.
For Windows Git Bash, use PowerShell instead, or set MSYS_NO_PATHCONV=1
and mount "$(pwd -W):/data" to avoid MSYS rewriting container paths.
Prefer a language client? See Python or JavaScript. To build the CLI itself, follow Contributing.
Build a graph you can check
Our graph says that an application depends on a web library, which depends on
a logging library. The logging library has a vulnerability. Save these three
RDF statements as data.nt:
<http://ex/app> <http://ex/dependsOn> <http://ex/web> .
<http://ex/web> <http://ex/dependsOn> <http://ex/logging> .
<http://ex/logging> <http://ex/hasVulnerability> <http://ex/CVE-2099-0001> .
For a copy-and-paste setup in a POSIX shell:
cat > data.nt <<'EOF'
<http://ex/app> <http://ex/dependsOn> <http://ex/web> .
<http://ex/web> <http://ex/dependsOn> <http://ex/logging> .
<http://ex/logging> <http://ex/hasVulnerability> <http://ex/CVE-2099-0001> .
EOF
Or in PowerShell:
@'
<http://ex/app> <http://ex/dependsOn> <http://ex/web> .
<http://ex/web> <http://ex/dependsOn> <http://ex/logging> .
<http://ex/logging> <http://ex/hasVulnerability> <http://ex/CVE-2099-0001> .
'@ | Set-Content -Encoding ascii data.nt
Now pack the RDF and include a Dataset Card:
rete build data.nt -o data.rete --card --title "My dependency graph"
The build reports 3 triples and 6 terms, and writes data.rete next to
data.nt. It also reports embedding the card, measuring starter queries, and
writing build information. Exact metadata sizes and timings can vary.
The file contains a dictionary and query indexes, plus a community summary when built with a pyramid. It is an immutable snapshot: changing the RDF means building another file. Check Compatibility before exchanging files with older readers; the file-format generation and project release version are separate.
For your own data, the CLI also accepts N-Quads, Turtle, TriG, RDF/XML
(including RDF/XML .owl files), Jelly (.jelly), JSON-LD (.jsonld) and YAML-LD (.yamlld). N-Quads can preserve named graphs.
OWL/XML and Functional Syntax require conversion to RDF first. See
CLI build options for input formats, merged inputs, streaming,
compression, memory limits and optional indexes.
Ask a question and inspect the file
Which packages depend on logging, directly or through another package?
The + follows one or more dependsOn edges.
rete sparql data.rete "PREFIX e: <http://ex/> SELECT ?package WHERE { ?package e:dependsOn+ e:logging } ORDER BY ?package"
Expected output:
2 solution(s)
?package=<http://ex/app>
?package=<http://ex/web>
logging itself is absent: this query needs at least one dependency edge.
Query a .rete below shows the other ways to ask.
Inspect the description stored with the graph:
rete card data.rete
rete verify data.rete
The card begins with Dataset Card, title My dependency graph, 3 triples,
6 terms, and the http://ex/ vocabulary. Its predicate counts are 2 for
dependsOn and 1 for hasVulnerability. It also includes starter queries
and a separate build record. verify should report that the content hash
matches. See Dataset Cards for curated metadata and build
provenance.
Source syntax validation (validate), file integrity (verify) and
SHACL shape validation check different things.
Query a .rete
The same file answers the same SPARQL from the CLI, Python, JavaScript, a URL and the browser. Each example below uses the graph you just built. For the query language itself, see SPARQL support; for joins, reasoning and analysis, Query and analyze.
Python
pip install rete-graph==0.7.5
Save as query.py:
import rete_graph as rete
g = rete.open("data.rete")
rows = g.query("""
PREFIX e: <http://ex/>
SELECT ?package WHERE { ?package e:dependsOn+ e:logging } ORDER BY ?package""")
for row in rows:
print(row["package"].value)
print(g.quads, "triples")
python query.py
http://ex/app
http://ex/web
3 triples
The package is rete-graph; the module is rete_graph. query() returns one
dict per row, with each value a Term that has .value. See Python.
JavaScript
npm install rete-graph@0.7.5
Save as query.mjs:
import { readFileSync } from "node:fs";
import { open } from "rete-graph";
const g = await open(readFileSync("data.rete"));
const rows = g.query(`
PREFIX e: <http://ex/>
SELECT ?package WHERE { ?package e:dependsOn+ e:logging } ORDER BY ?package`);
for (const row of rows) console.log(row.package.value);
console.log(g.quads, "triples");
node query.mjs
http://ex/app
http://ex/web
3 triples
This runs in Node 18 or later. In a browser, open the bytes in a worker or fetch them yourself. See JavaScript.
Labels and words
A graph with rdfs:label literals can be searched by label prefix and by word.
Our dependency graph has none, so add three labels and build a second file with
both indexes:
cat > labels.nt <<'EOF'
<http://ex/app> <http://www.w3.org/2000/01/rdf-schema#label> "Shop app" .
<http://ex/web> <http://www.w3.org/2000/01/rdf-schema#label> "Web framework" .
<http://ex/logging> <http://www.w3.org/2000/01/rdf-schema#label> "Logging library" .
EOF
rete build data.nt labels.nt -o labelled.rete --card --title "My dependency graph" --label-index --text-index
rete search matches a label prefix, and --contains matches a word in any
literal:
rete search labelled.rete "Web"
rete search labelled.rete --contains library
Web framework <http://ex/web>
<http://ex/logging>
The first command is what autocomplete uses; the second finds the subject by content. Both flags are optional and cost file size; see the CLI reference.
What a query will read
rete cost previews the range reads a query needs, without running it. It is
most useful on a large or remote file:
rete cost data.rete "PREFIX e: <http://ex/> SELECT ?package WHERE { ?package e:dependsOn+ e:logging }"
query cost preview
source: data.rete
source kind: local
file bytes: 18221
current engine access: lazy-tiles
query predicates: <http://ex/dependsOn>
summary exact answer: unavailable (query shape is not exactly answerable from summary predicate totals)
summary overview: 18221 bytes in 2 range request(s) · skips index
routed pattern open: unavailable (query is not a single default-graph triple pattern)
lazy query open: 18221 bytes in 1 range request(s) · reads index
full query open: 18221 bytes in 2 range request(s) · reads index
index section: offset 18014 · len 184
note: SPARQL evaluation opens lazily (tile directories only) and range-fetches index tiles as the query touches them; the full query-open figure is the eager upper bound.
The graph is 18 KB, so the whole file is one read. On a large file the lazy open reads the first 128 KiB and the query then reads only the tiles it needs.
Several files
rete federate runs one query over several files, local paths and URLs mixed,
and merges the rows. Build a second file with one more dependency:
echo '<http://ex/api> <http://ex/dependsOn> <http://ex/logging> .' > more.nt
rete build more.nt -o more.rete
rete federate data.rete more.rete --query "PREFIX e: <http://ex/> SELECT ?package WHERE { ?package e:dependsOn e:logging }"
data.rete: 1 row(s) in 2.2ms
more.rete: 1 row(s) in 2.5ms
2 solution(s)
federated 2 source(s): 2 queried, 0 pruned (routing on); 2 merged result(s)
?package=<http://ex/web>
?package=<http://ex/api>
Rows come in source order and are not re-sorted, because each file is queried on
its own: ORDER BY, COUNT and LIMIT apply per file. The CLI does a union
and no joins across files; the playground can join across sources. See
Federated queries.
A file on a URL
A remote file is queried through HTTP range requests, so nothing is downloaded
beyond what the query reads. To try it without a host, serve this directory with
the repository's range-aware dev server,
scripts/range_server.py
(Python's http.server ignores Range). Here it runs in a container, after
copying range_server.py into the directory:
docker run -d --name qs-range -p 8000:8000 -v "$PWD:/srv:ro" -w /srv python:3.12-slim python range_server.py 8000 /srv
rete sparql-url http://host.docker.internal:8000/data.rete "PREFIX e: <http://ex/> SELECT ?package WHERE { ?package e:dependsOn+ e:logging } ORDER BY ?package"
docker rm -f qs-range
(host.docker.internal is the host as seen from Docker Desktop. A native rete
uses 127.0.0.1.)
?package=<http://ex/app>
?package=<http://ex/web>
2 solution(s)
(fetched 18221 bytes in 1 range request(s); file is 18221 bytes)
The last line says what it fetched. This file is small, so it was read whole in one request. On a 106 MB graph, the build tutorial shows a lookup that read about 3% of it.
The browser
The playground runs the same queries in a page, with no
install. Open a catalog dataset, or add your own file by URL under
+ Add source. A browser needs the host to send CORS headers as well as
honor Range; see Hosting.
Put the file on a URL
Upload data.rete to a host that supports HTTP byte ranges, then query it as in
A file on a URL, replacing the example address with yours:
rete sparql-url https://your-host.example/data.rete "PREFIX e: <http://ex/> SELECT ?package WHERE { ?package e:dependsOn+ e:logging } ORDER BY ?package"
Use Hosting to check range responses, caching and browser CORS. The shared CLI/Python/R HTTP reader can retain a bounded whole-file response from a host that ignores ranges; it refuses oversized responses. A range-capable host is the reliable choice for large files.
Continue with the playground, the dependency-impact scenario, the build tutorial (Python and CLI, the card, the file layout, time and memory), or tables and large builds. Source builds, synthetic fixtures and test commands belong in Contributing.