federated-planning

sparq-fedplan — cost-based federated source selection + join planning

sparq-fedplan plans a federated SPARQL Basic Graph Pattern (BGP) across several remote endpoints from statistics already in hand — it never contacts the network. A caller fetches each source's descriptor once (the W3C VoID document a sparq-server serves at /.well-known/void, including the mined scs: characteristic sets), and the planner decides, deterministically:

1. which sources can contribute to each triple pattern, and
2. a join order + per-join bind-vs-hash algorithm over the selected sources.

It is the opt-in public surface for cost-based federation planning. Add it explicitly and enable the fedplan feature; it is not in sparq's default build (sparq-core/sparq-engine stay lean, the wasm artifact is unchanged unless you pull it in). There is no sparq-core/sparq-engine dependency — it plans over descriptors only.

Add the dependency

[dependencies]
sparq-fedplan = { path = "crates/sparq-fedplan", features = ["fedplan"] }
oxrdf = { version = "0.3", features = ["rdf-12"] }

The whole planner is behind the fedplan feature (off by default), so even a crate that depends on sparq-fedplan pays nothing for it unless the feature is enabled.

Build source descriptors

Either programmatically via the builder, or by parsing the served N-Triples document.

// `SourceDescriptorBuilder` is the (public, nameable) return type of `.builder(..)`; you only
// need to import it if you hold the builder in a `let` rather than chaining straight to `.build()`.
use sparq_fedplan::{SourceDescriptor, SourceDescriptorBuilder, SourceId, PredPartition, ClassPartition};

// Programmatic (VoID property/class partitions).
let src = SourceDescriptor::builder(SourceId::new("https://a.example/sparql"))
    .total_triples(10_000)
    .predicate(PredPartition { predicate: "http://xmlns.com/foaf/0.1/knows".into(),
        triples: 2000, distinct_subjects: 1000, distinct_objects: 1800 })
    .class(ClassPartition { class: "http://xmlns.com/foaf/0.1/Person".into(), entities: 1000 })
    .build();

// Or parse the served descriptor (the /.well-known/void N-Triples form, with scs: sets):
let parsed = SourceDescriptor::from_void_nt(SourceId::new("https://b.example/sparql"), nt)?;