data-formats

sparq data formats

How to get RDF into a sparq Graph and how to snapshot one cheaply. Text formats (Turtle / N-Triples / N-Quads / TriG) and the in-memory + streaming + external-memory loaders live in sparq-core; the binary HDT archive format (including content-sniffed .hdt.gz / .hdt.zst / .hdt.bz2) lives in the opt-in sparq-hdt crate.

Direction note: these crates parse RDF in. To write RDF out, sparq-engine ships the RDF writer matrix behind its opt-in serialize-rdf feature — Turtle / TriG / N-Quads / JSON-LD 1.1 writers (sparq_engine::serialize::*), plus deterministic pretty (indented) variants — Turtle / TriG (graph_to_turtle_pretty, the long-term engine home for the site formatter) and JSON-LD (graph_to_jsonld_pretty); the N-Triples writer (triples_to_ntriples) is always on. See recipe 6.

Quickstart

Add the dependency (HDT is a separate, native-only crate):

# Cargo.toml
[dependencies]
sparq-core = "0.1"            # default features include `parallel` (native)
sparq-hdt  = "0.1"            # OPTIONAL — only if you load .hdt archives
# To filter an HDT during its SPO decode instead of building the full Graph:
# sparq-hdt = { version = "0.1", features = ["load-filter"] }
oxrdf      = { version = "0.3", features = ["rdf-12"] }  # for Term/NamedNode at call sites

use sparq_core::Graph;

// `format` (plus media-type aliases): "turtle"|"ttl"|"text/turtle"|"application/turtle" |
//   "ntriples"|"n-triples"|"nt"|"application/n-triples" | "nquads"|"n-quads"|"nq"|"application/n-quads" |
//   "trig"|"application/trig". An UNRECOGNISED format string is an `Err` — NOT silently
//   parsed as Turtle (sq-m2pc). JSON-LD ("jsonld"/"json-ld"/"application/ld+json") needs the
//   `jsonld` feature on the `sparq-core` LIBRARY dep (OFF by default — the library stays lean);
//   without it those strings also error rather than mis-parsing. [OPUS-4.8] sq-oy1f.4: the
//   `sparq-cli` and `sparq-server` BINARIES enable `jsonld` by DEFAULT (a maintainer-directed
//   exception), so they read/write JSON-LD out of the box; a library embedder opts in explicitly.
//   [OPUS-4.8] sq-f47w1 (survey §B1): RDF/XML ("rdfxml"/"rdf-xml"/"application/rdf+xml")
//   likewise needs the OPT-IN `rdfxml` feature on `sparq-core` (OFF by default — it links
//   `oxrdfxml`/`quick-xml`, kept off the lean wasm bundle); without it those strings error
//   rather than mis-parsing. RDF/XML has no named-graph syntax, so it loads via `load_str` /
//   `parse_to_triples` (not the dataset path), serial-only (XML is not line-delimited).
let ttl = r#"@prefix ex: <http://ex/> .
ex:alice ex:knows ex:bob ."#;
let g = Graph::load_str(ttl, "turtle").expect("parse");
assert_eq!(g.len(), 1);

// HDT archive (sniffs .hdt.gz/.hdt.zst/.hdt.bz2 by magic bytes, not file name):
// let g = sparq_hdt::load("dataset.hdt").unwrap();