Install or build from source

v0.1.6 release install paths

These are the install commands for the planned v0.1.6 release. Use them only after the tagged release and corresponding registry publications have succeeded. v0.1.5 published the three npm packages but not the PyPI wheels, and the crates.io bootstrap is still pending. Until then, build from source.

# Rust CLI and HTTP server
cargo install sparq-cli --version 0.1.6
cargo install sparq-server --version 0.1.6

# Rust libraries (run inside your Cargo project)
cargo add sparq-core@0.1.6 sparq-engine@0.1.6

# Python: distribution name sparq-rdf, import name sparq
python -m pip install sparq-rdf==0.1.6
python -c 'import sparq'

# JavaScript/WASM RDF store
npm install @sparq-org/sparq@0.1.6
# Loopback-only Solid/LDP development host (not a production server)
npm install @sparq-org/solid-server@0.1.6
# eye-js / eyereasoner migration API backed by sparq's N3 reasoner
npm install @sparq-org/eyereasoner-compat@0.1.6

Build from source

sparq is a Rust workspace. The minimum supported Rust version (MSRV) is tracked in CI; a recent stable toolchain works. Build the release binaries, then query a file, build a persistent on-disk store, or run the HTTP server:

cargo build --release

# Query a file (Turtle / N-Triples / N-Quads / TriG, optionally .gz / .bz2 / .zst)
cargo run --release -p sparq-cli -- query data.ttl turtle \
  'SELECT ?s ?o WHERE { ?s <http://schema.org/name> ?o } LIMIT 10'

# Build a persistent on-disk store once, then query it without loading into RAM
cargo run --release -p sparq-cli -- build data.nt ntriples ./idx
cargo run --release -p sparq-cli -- query-mmap ./idx 'SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }'

# W3C SPARQL Protocol HTTP server on :3030
cargo run --release -p sparq-server -- --addr 127.0.0.1:3030 --format turtle data.ttl

Use it as a library

The snippet below is not hand-written prose — it is the quickstart region of crates/sparq-engine/examples/quickstart.rs, embedded verbatim via mdBook's {{#rustdoc_include}}. That file is compiled and run by cargo test -p sparq-engine --examples, so this example cannot silently drift from the public API:

//! sq-384j — Tested library quickstart, embedded into the docs guide.
//!
//! This is the canonical "use sparq as a library" example. The region between the
//! `book/src/getting-started/install.md` via mdBook's `{{#rustdoc_include}}`, so the
//! snippet a reader sees in the guide is a fragment of THIS file — a file that
//! `cargo test -p sparq-engine --examples` actually compiles and runs (see the
//! `#[test]` below). Keep the anchored region self-contained and dependency-light
//! (only `sparq-core` + `sparq-engine`, both already direct deps of this crate) so
//! the guide example stays honest and never drifts from a passing test.
//!
//! Run it directly with:
//!   cargo run -p sparq-engine --example quickstart

use sparq_core::Graph;
use sparq_engine::query;

fn count_people(turtle: &str) -> Result<usize, String> {
    // Parse RDF (Turtle/N-Triples/N-Quads/TriG) straight from a string.
    let graph = Graph::load_str(turtle, "turtle")?;

    // Run a SPARQL 1.1 SELECT. The result exposes `vars` (the projected
    // variables) and `rows` (each a `Vec<Option<Term>>`, one cell per var).
    let result = query(
        &graph,
        "SELECT ?person WHERE { ?person a <http://schema.org/Person> }",
    )?;

    Ok(result.rows.len())
}

fn main() {
    let turtle = r#"
        @prefix schema: <http://schema.org/> .
        <http://example.org/alice> a schema:Person .
        <http://example.org/bob>   a schema:Person .
        <http://example.org/acme>  a schema:Organization .
    "#;

    let n = count_people(turtle).expect("query should succeed");
    println!("{n} people");
}

#[cfg(test)]
mod tests {
    use super::count_people;

    // The same code path the docs guide shows, exercised by `cargo test`. If the
    // public API drifts, this test (and therefore the embedded guide snippet)
    // breaks loudly rather than silently going stale.
    #[test]
    fn quickstart_counts_people() {
        let turtle = r#"
            @prefix schema: <http://schema.org/> .
            <http://example.org/alice> a schema:Person .
            <http://example.org/bob>   a schema:Person .
            <http://example.org/acme>  a schema:Organization .
        "#;
        assert_eq!(count_people(turtle).unwrap(), 2);
    }
}

The contributor gate

If you are working on the engine itself, the gate for landing a change is a green full-workspace build, test, lint, and the conformance / performance ratchets:

cargo build --workspace
cargo test  --workspace
cargo clippy --workspace --exclude sparq-py --all-targets -- -D warnings

cargo fmt --all --check runs in CI too, but it is informational, not part of the gate: the one-time workspace reformat is still pending, so the check reports pre-existing diffs in files you did not touch. Format what you touched and leave the rest.

See CONTRIBUTING.md for the full contributor workflow and the conformance ratchet details — that file is the canonical source for the gate.