Craqle

Craqle is a Rust library for storing, editing, validating, searching, and replicating RO-Crates as RDF named graphs. It supports SPARQL queries and updates, SHACL validation, Tantivy full-text search, and RO-Crate JSON-LD import and export.

Each graph is stored in an Observed-Remove Set (OR-Set) RDF CRDT Database that can be asynchronously synchronized between machines. Inserts are tagged with actor-and-counter dots, while deletions remove only the dots included in their observed vector clock. This preserves concurrent inserts, makes event replay idempotent, and ensures that replicas with the same causal event history converge without a central write coordinator.

Every graph maps to a deterministic Irokle topic. Craqle publishes local operation batches durably before applying them to its RDF projection, allowing recovery after restarts and reconciliation with peers. Authorization remains under the host application’s control, and visible crates that fail validation are not exported.

Features

• Store RO-Crates as named RDF graphs backed by a durable, convergent OR-Set CRDT.
• Query and update authorized graph sets with SPARQL.
• Validate graph state with SHACL and ensure that Crates adhere to a specific shape.
• Run full-text search with Tantivy and hydrate matches from RDF properties.
• Synchronize graph state across machines with convergent replication through durable per-graph Irokle topics.
• Control graph access through host-provided authorizers and persisted policies.

Craqle 0.3 requires Rust 1.97.1 and integrates Irokle 0.3.0. See the upgrade notes before opening an existing database.

Open a node

The examples below build on this setup:

use craqle::{AllowAllAuthorizer, CraqleNode};

let node = CraqleNode::open("./data/craqle")?;
let auth = AllowAllAuthorizer;

Craqle uses SyncAll local persistence by default. Buffer mode is an explicit choice for tests, bulk fixture loading, or deployments whose external log already provides the required durability guarantee.

Create a crate

use craqle::{CreateCrateRequest, GraphId, GraphPolicy};

let graph = GraphId::new("urn:crate:proteomics");
node.create_crate(
    &auth,
    CreateCrateRequest::new(
        graph.clone(),
        "Proteomics Study",
        "Mass spectrometry data and analysis",
        "2026-08-22",
        None,
        GraphPolicy::default(),
    ),
)?;

Add data

node.add_data_entity(
    &auth,
    &graph,
    "data/run-01.fastq.gz",
    "http://schema.org/MediaObject",
    "Run 01 FASTQ",
)?;

Import and export JSON-LD

let document = std::fs::read_to_string("ro-crate-metadata.json")?;
let imported = GraphId::new("urn:crate:imported");

node.apply_rocrate_document_with_policy(
    &auth,
    imported.clone(),
    &document,
    GraphPolicy::default(),
)?;

let jsonld = node.export_rocrate(&auth, &imported)?;

Query with SPARQL

let results = node.query(
    &auth,
    "SELECT ?entity ?name WHERE {
       ?entity <http://schema.org/name> ?name
     }",
)?;

Select the exact graphs used by a query:

let results = node.query_in_graphs(
    &auth,
    &[graph.clone(), imported.clone()],
    "SELECT ?graph ?name WHERE {
       GRAPH ?graph {
         ?entity <http://schema.org/name> ?name
       }
     }",
)?;

Prepare a query for repeated execution:

use craqle::QueryOptions;

let prepared = node.prepare_query(
    "SELECT ?name WHERE { ?entity <http://schema.org/name> ?name }",
)?;
let execution =
    node.execute_prepared(&auth, &prepared, &QueryOptions::results_only())?;

QueryOptions::default() also collects per-operator statistics for analysis, which costs several times more than the query itself on join-heavy queries. Use QueryOptions::results_only() when only the rows are needed.

Queries enforce limits on input, storage reads, native execution, and collected results by default. Generic sorting, grouping, joins, and property paths remain supported, but the upstream evaluator's internal buffers are not fully accounted for and cancellation inside those operators is cooperative. These limits are not a process memory ceiling. Trusted workloads can select QueryLimits::unbounded() through QueryOptions to remove the configurable resource ceilings.

Update with SPARQL

node.apply_sparql_update(
    &auth,
    r#"
      INSERT DATA {
        GRAPH <urn:crate:proteomics> {
          <urn:crate:proteomics>
            <http://schema.org/keywords>
            "proteomics"
        }
      }
    "#,
)?;

Search

use craqle::SearchRequest;

let hits = node.search(
    &auth,
    SearchRequest {
        query: "proteomics",
        limit: 10,
    },
)?;

let resources = node.search_resources(
    &auth,
    SearchRequest {
        query: "workflow",
        limit: 10,
    },
)?;

Search indexing is asynchronous. flush_search_updates() waits for work accepted before the call, plus any recovery that work requires. flush_search() accepts SearchFlushOptions for a timeout or cancellation and returns a coverage receipt. A timed-out or cancelled wait leaves durable indexing work queued. Search-disabled builds retain that work and return Unsupported from search and flush calls.

Dropping a node joins its maintenance thread. shutdown(timeout) returns ShutdownState::TimedOut if the thread has not finished; the node retains the thread and a later shutdown or drop still joins it.

Validate with SHACL

use craqle::{ShaclCompileOptions, ShaclValidationOptions};

let schema = node.compile_shacl(
    &auth,
    &shapes_graph,
    &ShaclCompileOptions::default(),
)?;
let report = node.validate_shacl(
    &auth,
    &data_graph,
    &schema,
    &ShaclValidationOptions::default(),
)?;

Bind shapes to a graph and enforce them on writes:

use craqle::{
    ShaclBinding, ShaclBindingOptions, ShaclWritePolicy,
};

node.bind_shacl(
    &auth,
    &ShaclBinding {
        data_graph: data_graph.clone(),
        shapes_graph: shapes_graph.clone(),
        policy: ShaclWritePolicy::Enforce,
        validation_options: ShaclBindingOptions::default(),
    },
)?;

let statuses = node.shacl_binding_statuses(&auth, &data_graph)?;

Use application permissions

use craqle::{GrantAuthorizer, PermissionGrant, PermissionLevel};

let writer = GrantAuthorizer::new(vec![PermissionGrant::new(
    "/datasets/project-a/**",
    PermissionLevel::Write,
)]);

node.create_crate(
    &writer,
    CreateCrateRequest::new(
        GraphId::new("urn:crate:project-a"),
        "Project A",
        "Authorized project data",
        "2026-08-22",
        None,
        GraphPolicy {
            public: false,
            permission_paths: vec!["/datasets/project-a/crate".to_string()],
        },
    ),
)?;

Runnable examples

cargo run --example demo
cargo run --all-features --example api_workflow

See examples/demo.rs for a small create/export/search workflow and examples/api_workflow.rs for a complete create/import/query/update/SHACL workflow.