Skip to content

Rust getting started

This guide gets Rust users from install to common workflows. Python users have a complete, independent Python documentation track.

Install the toolchain

Oxiland requires Rust 1.87+ (edition 2024).

rustup update stable
rustc --version   # >= 1.87

If your organization pins an older toolchain, you cannot evaluate the Rust crate until that pin moves; this is intentional for the Oxigraph 0.5.9 compatibility matrix. The Python package only needs CPython 3.10–3.14.

For a Rust-only application, no system Oxigraph or Redland library is required.

Create a project and add the dependency

cargo new hello-oxiland
cd hello-oxiland

Tip 0.13.0 is the current package version.

Published / tip pin:

[dependencies]
oxiland = "0.13.0"

Tip (git or path):

[dependencies]
oxiland = { git = "https://github.com/eddiethedean/oxiland" }

Optional: enable features = ["tracing"] to bridge World logging to the tracing crate. Install the CLI separately with cargo install oxiland-cli (see the CLI guide).

Workflow 1 — Build a model and ASK

use oxiland::terms::{Literal, Triple, named_node};
use oxiland::{Model, Query, QueryResults};

fn main() -> oxiland::Result<()> {
    let model = Model::new()?;
    model.add(Triple::new(
        named_node("https://example.com/alice")?,
        named_node("https://example.com/name")?,
        Literal::new_simple_literal("Alice"),
    ))?;

    let ask = Query::new("ASK { ?s ?p ?o }").execute(&model)?;
    assert!(matches!(ask, QueryResults::Boolean(true)));
    Ok(())
}

From a checkout: cargo run --example quick_start.

Workflow 2 — SELECT bindings

use oxiland::terms::{Literal, Triple, named_node};
use oxiland::{Model, Query, QueryResults};

fn main() -> oxiland::Result<()> {
    let model = Model::new()?;
    model.add(Triple::new(
        named_node("https://example.com/alice")?,
        named_node("https://example.com/name")?,
        Literal::new_simple_literal("Alice"),
    ))?;

    let results = Query::new(
        "SELECT ?name WHERE { <https://example.com/alice> <https://example.com/name> ?name }",
    )
    .execute(&model)?;

    match results {
        QueryResults::Solutions(solutions) => {
            for solution in solutions {
                let solution = solution
                    .map_err(|error| oxiland::Error::SparqlEvaluation(error.to_string()))?;
                if let Some(term) = solution.get("name") {
                    println!("name = {term}");
                }
            }
        }
        _other => panic!("expected SELECT solutions"),
    }
    Ok(())
}

From a checkout: cargo run --example select. Details: SPARQL.

Workflow 3 — Parse Turtle and write N-Triples

use oxiland::io::{Parser, Serializer, Syntax};
use oxiland::Model;

fn main() -> oxiland::Result<()> {
    let model = Model::new()?;
    Parser::for_syntax(Syntax::Turtle)
        .base_iri("https://example.com/")?
        .load_collecting(&model, b"<alice> <name> \"Alice\" .".as_slice())?;

    let out = Serializer::for_syntax(Syntax::NTriples).serialize_model_to_string(&model)?;
    println!("{out}");
    Ok(())
}

From a checkout: cargo run --example parse_serialize.

Choose storage deliberately

Model::new() is process-local and disappears when the model is dropped. Model::open(path) creates or opens a persistent local store. For production, prefer typed OpenOptions with create(false) so a missing configured store fails instead of initializing an empty dataset.

See Persistence and Rust production operations before deploying durable state.

Handle errors by category

Application code can use oxiland::Result<T> and match Error variants at a boundary. Avoid matching diagnostic strings. Parse errors, SPARQL parse errors, evaluation failures, storage failures, I/O errors, and unsupported capabilities have separate variants.

Errors may occur while advancing lazy RDF or SPARQL iterators, so handle the item-level Result rather than assuming iterator construction validates all input.

Python package

Prefer an isolated environment, then install with the module form of pip:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
python -m pip install oxiland

Published wheels track the latest release. Start with the Python overview, then use the dedicated guides for installation, models, RDF I/O and SPARQL, and production operations.